<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow: util/util_fwd.hpp Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="dir_23ec12649285f9fabf3a6b7380226c28.html">util</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle"><div class="title">util_fwd.hpp</div></div>
</div><!--header-->
<div class="contents">
<a href="util__fwd_8hpp.html">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a id="l00001" name="l00001"></a><span class="lineno">    1</span><span class="comment">/* Flow</span></div>
<div class="line"><a id="l00002" name="l00002"></a><span class="lineno">    2</span><span class="comment"> * Copyright 2023 Akamai Technologies, Inc.</span></div>
<div class="line"><a id="l00003" name="l00003"></a><span class="lineno">    3</span><span class="comment"> *</span></div>
<div class="line"><a id="l00004" name="l00004"></a><span class="lineno">    4</span><span class="comment"> * Licensed under the Apache License, Version 2.0 (the</span></div>
<div class="line"><a id="l00005" name="l00005"></a><span class="lineno">    5</span><span class="comment"> * &quot;License&quot;); you may not use this file except in</span></div>
<div class="line"><a id="l00006" name="l00006"></a><span class="lineno">    6</span><span class="comment"> * compliance with the License.  You may obtain a copy</span></div>
<div class="line"><a id="l00007" name="l00007"></a><span class="lineno">    7</span><span class="comment"> * of the License at</span></div>
<div class="line"><a id="l00008" name="l00008"></a><span class="lineno">    8</span><span class="comment"> *</span></div>
<div class="line"><a id="l00009" name="l00009"></a><span class="lineno">    9</span><span class="comment"> *   https://www.apache.org/licenses/LICENSE-2.0</span></div>
<div class="line"><a id="l00010" name="l00010"></a><span class="lineno">   10</span><span class="comment"> *</span></div>
<div class="line"><a id="l00011" name="l00011"></a><span class="lineno">   11</span><span class="comment"> * Unless required by applicable law or agreed to in</span></div>
<div class="line"><a id="l00012" name="l00012"></a><span class="lineno">   12</span><span class="comment"> * writing, software distributed under the License is</span></div>
<div class="line"><a id="l00013" name="l00013"></a><span class="lineno">   13</span><span class="comment"> * distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR</span></div>
<div class="line"><a id="l00014" name="l00014"></a><span class="lineno">   14</span><span class="comment"> * CONDITIONS OF ANY KIND, either express or implied.</span></div>
<div class="line"><a id="l00015" name="l00015"></a><span class="lineno">   15</span><span class="comment"> * See the License for the specific language governing</span></div>
<div class="line"><a id="l00016" name="l00016"></a><span class="lineno">   16</span><span class="comment"> * permissions and limitations under the License. */</span></div>
<div class="line"><a id="l00017" name="l00017"></a><span class="lineno">   17</span><span class="comment"></span> </div>
<div class="line"><a id="l00018" name="l00018"></a><span class="lineno">   18</span><span class="comment">/// @file</span></div>
<div class="line"><a id="l00019" name="l00019"></a><span class="lineno">   19</span><span class="comment"></span><span class="preprocessor">#pragma once</span></div>
<div class="line"><a id="l00020" name="l00020"></a><span class="lineno">   20</span> </div>
<div class="line"><a id="l00021" name="l00021"></a><span class="lineno">   21</span><span class="preprocessor">#include &quot;<a class="code" href="detail_2util__fwd_8hpp.html">flow/util/detail/util_fwd.hpp</a>&quot;</span></div>
<div class="line"><a id="l00022" name="l00022"></a><span class="lineno">   22</span><span class="preprocessor">#include &lt;boost/asio.hpp&gt;</span></div>
<div class="line"><a id="l00023" name="l00023"></a><span class="lineno">   23</span><span class="preprocessor">#include &lt;boost/thread.hpp&gt;</span></div>
<div class="line"><a id="l00024" name="l00024"></a><span class="lineno">   24</span><span class="preprocessor">#include &lt;boost/thread/null_mutex.hpp&gt;</span></div>
<div class="line"><a id="l00025" name="l00025"></a><span class="lineno">   25</span><span class="preprocessor">#include &lt;iostream&gt;</span></div>
<div class="line"><a id="l00026" name="l00026"></a><span class="lineno">   26</span><span class="preprocessor">#include &lt;memory&gt;</span></div>
<div class="line"><a id="l00027" name="l00027"></a><span class="lineno">   27</span><span class="comment"></span> </div>
<div class="line"><a id="l00028" name="l00028"></a><span class="lineno">   28</span><span class="comment">/**</span></div>
<div class="line"><a id="l00029" name="l00029"></a><span class="lineno">   29</span><span class="comment"> * Flow module containing miscellaneous general-use facilities that don&#39;t fit into any other Flow module.</span></div>
<div class="line"><a id="l00030" name="l00030"></a><span class="lineno">   30</span><span class="comment"> *</span></div>
<div class="line"><a id="l00031" name="l00031"></a><span class="lineno">   31</span><span class="comment"> * Each symbol therein is typically used by at least 1 other Flow module; but all public symbols (except ones</span></div>
<div class="line"><a id="l00032" name="l00032"></a><span class="lineno">   32</span><span class="comment"> * under a detail/ subdirectory) are intended for use by Flow user as well.</span></div>
<div class="line"><a id="l00033" name="l00033"></a><span class="lineno">   33</span><span class="comment"> *</span></div>
<div class="line"><a id="l00034" name="l00034"></a><span class="lineno">   34</span><span class="comment"> * @todo Since Flow gained its first users beyond the original author, some Flow-adjacent code has been written from</span></div>
<div class="line"><a id="l00035" name="l00035"></a><span class="lineno">   35</span><span class="comment"> * which Flow can benefit, including additions to flow::util module.  (Flow itself continued to be developed, but some</span></div>
<div class="line"><a id="l00036" name="l00036"></a><span class="lineno">   36</span><span class="comment"> * features were added elsewhere for expediency; this is a reminder to factor them out into Flow for the benefit of</span></div>
<div class="line"><a id="l00037" name="l00037"></a><span class="lineno">   37</span><span class="comment"> * all.)  Some features to migrate here might be: conversion between boost.chrono and std.chrono types; (add more</span></div>
<div class="line"><a id="l00038" name="l00038"></a><span class="lineno">   38</span><span class="comment"> * here).</span></div>
<div class="line"><a id="l00039" name="l00039"></a><span class="lineno">   39</span><span class="comment"> */</span></div>
<div class="line"><a id="l00040" name="l00040"></a><span class="lineno">   40</span><span class="keyword">namespace </span><a class="code hl_namespace" href="namespaceflow_1_1util.html">flow::util</a></div>
<div class="line"><a id="l00041" name="l00041"></a><span class="lineno">   41</span>{</div>
<div class="line"><a id="l00042" name="l00042"></a><span class="lineno">   42</span><span class="comment">// Types.</span></div>
<div class="line"><a id="l00043" name="l00043"></a><span class="lineno">   43</span> </div>
<div class="line"><a id="l00044" name="l00044"></a><span class="lineno">   44</span><span class="comment">// Find doc headers near the bodies of these compound types.</span></div>
<div class="line"><a id="l00045" name="l00045"></a><span class="lineno">   45</span> </div>
<div class="line"><a id="l00046" name="l00046"></a><span class="lineno">   46</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Key, <span class="keyword">typename</span> Mapped, <span class="keyword">typename</span> Hash = boost::hash&lt;Key&gt;, <span class="keyword">typename</span> Pred = std::equal_to&lt;Key&gt;&gt;</div>
<div class="line"><a id="l00047" name="l00047"></a><span class="lineno">   47</span><span class="keyword">class </span>Linked_hash_map;</div>
<div class="line"><a id="l00048" name="l00048"></a><span class="lineno">   48</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Key, <span class="keyword">typename</span> Hash = boost::hash&lt;Key&gt;, <span class="keyword">typename</span> Pred = std::equal_to&lt;Key&gt;&gt;</div>
<div class="line"><a id="l00049" name="l00049"></a><span class="lineno">   49</span><span class="keyword">class </span>Linked_hash_set;</div>
<div class="line"><a id="l00050" name="l00050"></a><span class="lineno">   50</span> </div>
<div class="line"><a id="l00051" name="l00051"></a><span class="lineno">   51</span><span class="keyword">class </span>Null_interface;</div>
<div class="line"><a id="l00052" name="l00052"></a><span class="lineno">   52</span> </div>
<div class="line"><a id="l00053" name="l00053"></a><span class="lineno">   53</span><span class="keyword">class </span>Rnd_gen_uniform_range_base;</div>
<div class="line"><a id="l00054" name="l00054"></a><span class="lineno">   54</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> range_t&gt;</div>
<div class="line"><a id="l00055" name="l00055"></a><span class="lineno">   55</span><span class="keyword">class </span>Rnd_gen_uniform_range;</div>
<div class="line"><a id="l00056" name="l00056"></a><span class="lineno">   56</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> range_t&gt;</div>
<div class="line"><a id="l00057" name="l00057"></a><span class="lineno">   57</span><span class="keyword">class </span>Rnd_gen_uniform_range_mt;</div>
<div class="line"><a id="l00058" name="l00058"></a><span class="lineno">   58</span> </div>
<div class="line"><a id="l00059" name="l00059"></a><span class="lineno">   59</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Value&gt;</div>
<div class="line"><a id="l00060" name="l00060"></a><span class="lineno">   60</span><span class="keyword">class </span>Scoped_setter;</div>
<div class="line"><a id="l00061" name="l00061"></a><span class="lineno">   61</span> </div>
<div class="line"><a id="l00062" name="l00062"></a><span class="lineno">   62</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Target_ptr,</div>
<div class="line"><a id="l00063" name="l00063"></a><span class="lineno">   63</span>         <span class="keyword">typename</span> Const_target_ptr</div>
<div class="line"><a id="l00064" name="l00064"></a><span class="lineno">   64</span>           = <span class="keyword">typename</span> std::pointer_traits&lt;Target_ptr&gt;::template rebind&lt;typename Target_ptr::element_type const&gt;&gt;</div>
<div class="line"><a id="l00065" name="l00065"></a><span class="lineno">   65</span><span class="keyword">class </span>Shared_ptr_alias_holder;</div>
<div class="line"><a id="l00066" name="l00066"></a><span class="lineno">   66</span> </div>
<div class="line"><a id="l00067" name="l00067"></a><span class="lineno">   67</span><span class="keyword">class </span>String_ostream;</div>
<div class="line"><a id="l00068" name="l00068"></a><span class="lineno">   68</span> </div>
<div class="line"><a id="l00069" name="l00069"></a><span class="lineno">   69</span><span class="keyword">class </span>Unique_id_holder;</div>
<div class="line"><a id="l00070" name="l00070"></a><span class="lineno">   70</span><span class="comment"></span> </div>
<div class="line"><a id="l00071" name="l00071"></a><span class="lineno">   71</span><span class="comment">/**</span></div>
<div class="line"><a id="l00072" name="l00072"></a><span class="lineno">   72</span><span class="comment"> * Short-hand for standard thread class.</span></div>
<div class="line"><a id="l00073" name="l00073"></a><span class="lineno">   73</span><span class="comment"> * We use/encourage use of boost.thread threads (and other boost.thread facilities) over std.thread counterparts --</span></div>
<div class="line"><a id="l00074" name="l00074"></a><span class="lineno">   74</span><span class="comment"> * simply because it tends to be more full-featured.  However, reminder: boost.thread IS (API-wise at least)</span></div>
<div class="line"><a id="l00075" name="l00075"></a><span class="lineno">   75</span><span class="comment"> * std.thread, plus more (advanced?) stuff.  Generally, boost.thread-using code can be converted to std.thread</span></div>
<div class="line"><a id="l00076" name="l00076"></a><span class="lineno">   76</span><span class="comment"> * with little pain, unless one of the &quot;advanced?&quot; features is used.</span></div>
<div class="line"><a id="l00077" name="l00077"></a><span class="lineno">   77</span><span class="comment"> */</span></div>
<div class="line"><a id="l00078" name="l00078"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#af030c3119f060a9630afca31098a78a5">   78</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#af030c3119f060a9630afca31098a78a5">Thread</a> = boost::thread;</div>
<div class="line"><a id="l00079" name="l00079"></a><span class="lineno">   79</span> </div>
<div class="line"><a id="l00080" name="l00080"></a><span class="lineno">   80</span><span class="comment">/* (The @namespace and @brief thingies shouldn&#39;t be needed, but some Doxygen bug necessitated them.</span></div>
<div class="line"><a id="l00081" name="l00081"></a><span class="lineno">   81</span><span class="comment"> * See flow::util::bind_ns for explanation... same thing here.) */</span></div>
<div class="line"><a id="l00082" name="l00082"></a><span class="lineno">   82</span><span class="comment"></span> </div>
<div class="line"><a id="l00083" name="l00083"></a><span class="lineno">   83</span><span class="comment">/**</span></div>
<div class="line"><a id="l00084" name="l00084"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util_1_1this__thread.html">   84</a></span><span class="comment"> * @namespace flow::util::this_thread</span></div>
<div class="line"><a id="l00085" name="l00085"></a><span class="lineno">   85</span><span class="comment"> * @brief Short-hand for standard this-thread namespace. Paired with util::Thread.</span></div>
<div class="line"><a id="l00086" name="l00086"></a><span class="lineno">   86</span><span class="comment"> */</span></div>
<div class="line"><a id="l00087" name="l00087"></a><span class="lineno">   87</span><span class="keyword">namespace </span>this_thread = boost::this_thread;</div>
<div class="line"><a id="l00088" name="l00088"></a><span class="lineno">   88</span><span class="comment"></span> </div>
<div class="line"><a id="l00089" name="l00089"></a><span class="lineno">   89</span><span class="comment">/// Short-hand for an OS-provided ID of a util::Thread.</span></div>
<div class="line"><a id="l00090" name="l00090"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a0a4e7b2d3107bd630e0dc0c0b8f2e4de">   90</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a0a4e7b2d3107bd630e0dc0c0b8f2e4de">Thread_id</a> = Thread::id;</div>
<div class="line"><a id="l00091" name="l00091"></a><span class="lineno">   91</span><span class="comment"></span> </div>
<div class="line"><a id="l00092" name="l00092"></a><span class="lineno">   92</span><span class="comment">/**</span></div>
<div class="line"><a id="l00093" name="l00093"></a><span class="lineno">   93</span><span class="comment"> * Short-hand for boost.asio event service, the central class of boost.asio.</span></div>
<div class="line"><a id="l00094" name="l00094"></a><span class="lineno">   94</span><span class="comment"> *</span></div>
<div class="line"><a id="l00095" name="l00095"></a><span class="lineno">   95</span><span class="comment"> * ### Naming ###</span></div>
<div class="line"><a id="l00096" name="l00096"></a><span class="lineno">   96</span><span class="comment"> * The reasons for the rename -- as opposed to simply calling it `Io_service` (historically it was indeed so named) --</span></div>
<div class="line"><a id="l00097" name="l00097"></a><span class="lineno">   97</span><span class="comment"> * are as follows.  To start, a later version of Boost (to which we eventually moved) realigned</span></div>
<div class="line"><a id="l00098" name="l00098"></a><span class="lineno">   98</span><span class="comment"> * boost.asio&#39;s API to match the feedback boost.asio received when submitted as a candidate for inclusion into</span></div>
<div class="line"><a id="l00099" name="l00099"></a><span class="lineno">   99</span><span class="comment"> * the official STL (sometime after C++17); in this reorg they renamed it from `io_service` to `io_context`.</span></div>
<div class="line"><a id="l00100" name="l00100"></a><span class="lineno">  100</span><span class="comment"> * That&#39;s not the actual reason but more of a symptom of similar reasoning to the following:</span></div>
<div class="line"><a id="l00101" name="l00101"></a><span class="lineno">  101</span><span class="comment"> *   - &quot;Service&quot; sounds like something that has its own thread(s) perhaps, which `io_service` actually doesn&#39;t;</span></div>
<div class="line"><a id="l00102" name="l00102"></a><span class="lineno">  102</span><span class="comment"> *     it *can* (and typically is) used to take over at least one thread, but that&#39;s not a part of its &quot;essence,&quot; so</span></div>
<div class="line"><a id="l00103" name="l00103"></a><span class="lineno">  103</span><span class="comment"> *     to speak.  I&#39;ve noticed that when boost.asio neophytes see &quot;service&quot; they intuitively draw incorrect assumptions</span></div>
<div class="line"><a id="l00104" name="l00104"></a><span class="lineno">  104</span><span class="comment"> *     about what it does, and then one must repeatedly dash those assumptions.</span></div>
<div class="line"><a id="l00105" name="l00105"></a><span class="lineno">  105</span><span class="comment"> *   - Furthermore (though apparently boost.asio guys didn&#39;t agree or didn&#39;t agree strongly enough) &quot;I/O&quot; implies</span></div>
<div class="line"><a id="l00106" name="l00106"></a><span class="lineno">  106</span><span class="comment"> *     an `io_service` is all about working with various input/output (especially networking).  While it&#39;s true</span></div>
<div class="line"><a id="l00107" name="l00107"></a><span class="lineno">  107</span><span class="comment"> *     that roughly 50% of the utility of boost.asio is its portable sockets/networking API, the other 50% is about</span></div>
<div class="line"><a id="l00108" name="l00108"></a><span class="lineno">  108</span><span class="comment"> *     its ability to flexibly execute user tasks in various threads; and, indeed, `io_service` *itself* is more about</span></div>
<div class="line"><a id="l00109" name="l00109"></a><span class="lineno">  109</span><span class="comment"> *     the latter 50% rather than the former.  Its two most basic and arguably oft-used features are simply</span></div>
<div class="line"><a id="l00110" name="l00110"></a><span class="lineno">  110</span><span class="comment"> *     `io_service::post()` (which executes the given task ASAP); and the `basic_waitable_timer` set of classes</span></div>
<div class="line"><a id="l00111" name="l00111"></a><span class="lineno">  111</span><span class="comment"> *     (which execute task at some specified point in the future).  Note these have nothing to do with networking or</span></div>
<div class="line"><a id="l00112" name="l00112"></a><span class="lineno">  112</span><span class="comment"> *     I/O of any kind.  The I/O comes from the &quot;I/O object&quot; classes/etc., such as `tcp::socket`, but those</span></div>
<div class="line"><a id="l00113" name="l00113"></a><span class="lineno">  113</span><span class="comment"> *     are *not* `io_service`; they merely work together with it to execute the user-specified success/failure handlers.</span></div>
<div class="line"><a id="l00114" name="l00114"></a><span class="lineno">  114</span><span class="comment"> *</span></div>
<div class="line"><a id="l00115" name="l00115"></a><span class="lineno">  115</span><span class="comment"> * So, neither &quot;I/O&quot; nor &quot;service&quot; is accurate.  To fix both, then, we used this rename reasoning:</span></div>
<div class="line"><a id="l00116" name="l00116"></a><span class="lineno">  116</span><span class="comment"> *   - &quot;I/O&quot; can be replaced by the notion of it executing &quot;tasks.&quot;  boost.asio doesn&#39;t use or define the &quot;task&quot; term,</span></div>
<div class="line"><a id="l00117" name="l00117"></a><span class="lineno">  117</span><span class="comment"> *     sticking to &quot;handler&quot; or &quot;functor&quot; or &quot;function,&quot; but we feel it&#39;s a reasonable term in this context.</span></div>
<div class="line"><a id="l00118" name="l00118"></a><span class="lineno">  118</span><span class="comment"> *     (Function, etc., doesn&#39;t cover all possibilities.  Handler is OK, but when it&#39;s not in response to any event --</span></div>
<div class="line"><a id="l00119" name="l00119"></a><span class="lineno">  119</span><span class="comment"> *     as with vanilla `post()` -- what is it handling?)</span></div>
<div class="line"><a id="l00120" name="l00120"></a><span class="lineno">  120</span><span class="comment"> *   - &quot;Service&quot; is trickier to replace.  It&#39;s a battle between &quot;too generic&quot; and &quot;too specific and therefore long to</span></div>
<div class="line"><a id="l00121" name="l00121"></a><span class="lineno">  121</span><span class="comment"> *     type.&quot;  Plus there&#39;s the usual danger of accidentally overloading a term already used elsewhere nearby.</span></div>
<div class="line"><a id="l00122" name="l00122"></a><span class="lineno">  122</span><span class="comment"> *     Some ideas considered were: manager, engine, execution engine, queue, queues, context (which boost.asio chose),</span></div>
<div class="line"><a id="l00123" name="l00123"></a><span class="lineno">  123</span><span class="comment"> *     and various abbreviations thereof.  Ultimately it came down to context vs. engine, and I chose engine because</span></div>
<div class="line"><a id="l00124" name="l00124"></a><span class="lineno">  124</span><span class="comment"> *     context is just a little vague, or it suggests an arbitrary grouping of things -- whereas &quot;engine&quot; actually</span></div>
<div class="line"><a id="l00125" name="l00125"></a><span class="lineno">  125</span><span class="comment"> *     implies action: want to express this thing provides logical/algorithmic value as opposed to just bundling</span></div>
<div class="line"><a id="l00126" name="l00126"></a><span class="lineno">  126</span><span class="comment"> *     stuff together as &quot;context&quot; objects often do (e.g., &quot;SSL context&quot; in openssl).  Indeed `io_service` does provide</span></div>
<div class="line"><a id="l00127" name="l00127"></a><span class="lineno">  127</span><span class="comment"> *     immense algorithmic value.</span></div>
<div class="line"><a id="l00128" name="l00128"></a><span class="lineno">  128</span><span class="comment"> *     - Manager: generic but not bad; clashes with &quot;Windows task manager&quot; and such.</span></div>
<div class="line"><a id="l00129" name="l00129"></a><span class="lineno">  129</span><span class="comment"> *     - Execution engine: good but long.</span></div>
<div class="line"><a id="l00130" name="l00130"></a><span class="lineno">  130</span><span class="comment"> *     - Queue: early candidate, but at the very least it&#39;s not a *single* queue; if there are multiple threads</span></div>
<div class="line"><a id="l00131" name="l00131"></a><span class="lineno">  131</span><span class="comment"> *       `io_context::run()`ning then to the extent there are any queues there might be multiple.</span></div>
<div class="line"><a id="l00132" name="l00132"></a><span class="lineno">  132</span><span class="comment"> *     - Queues, qs: better... but having a thing called `Task_qs` -- of which there could be multiple (plural) --</span></div>
<div class="line"><a id="l00133" name="l00133"></a><span class="lineno">  133</span><span class="comment"> *       was clumsy.  (An early proof-of-concept used `Task_qs`; people were not fans.)</span></div>
<div class="line"><a id="l00134" name="l00134"></a><span class="lineno">  134</span><span class="comment"> */</span></div>
<div class="line"><a id="l00135" name="l00135"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#ac3e89a8a271b0ddc76ac2a0ce488dea4">  135</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#ac3e89a8a271b0ddc76ac2a0ce488dea4">Task_engine</a> = boost::asio::io_context;</div>
<div class="line"><a id="l00136" name="l00136"></a><span class="lineno">  136</span><span class="comment"></span> </div>
<div class="line"><a id="l00137" name="l00137"></a><span class="lineno">  137</span><span class="comment">/// Short-hand for boost.asio strand, an ancillary class that works with #Task_engine for advanced task scheduling.</span></div>
<div class="line"><a id="l00138" name="l00138"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#aa59354ab408e978c8a7bda1a4706924e">  138</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#aa59354ab408e978c8a7bda1a4706924e">Strand</a> = Task_engine::strand;</div>
<div class="line"><a id="l00139" name="l00139"></a><span class="lineno">  139</span><span class="comment"></span> </div>
<div class="line"><a id="l00140" name="l00140"></a><span class="lineno">  140</span><span class="comment">/**</span></div>
<div class="line"><a id="l00141" name="l00141"></a><span class="lineno">  141</span><span class="comment"> * boost.asio timer.  Can schedule a function to get called within a set amount of time or at</span></div>
<div class="line"><a id="l00142" name="l00142"></a><span class="lineno">  142</span><span class="comment"> * a certain specific time relative to some Epoch.</span></div>
<div class="line"><a id="l00143" name="l00143"></a><span class="lineno">  143</span><span class="comment"> *</span></div>
<div class="line"><a id="l00144" name="l00144"></a><span class="lineno">  144</span><span class="comment"> * @see schedule_task_from_now() (and friends) for a simpler task-scheduling API (which internally uses this</span></div>
<div class="line"><a id="l00145" name="l00145"></a><span class="lineno">  145</span><span class="comment"> *      `Timer).  The notes below still apply however.  Please read them even if you won&#39;t use `Timer` directly.</span></div>
<div class="line"><a id="l00146" name="l00146"></a><span class="lineno">  146</span><span class="comment"> *</span></div>
<div class="line"><a id="l00147" name="l00147"></a><span class="lineno">  147</span><span class="comment"> * Important: While one can schedule events using very precise units using #Fine_duration, the</span></div>
<div class="line"><a id="l00148" name="l00148"></a><span class="lineno">  148</span><span class="comment"> * timer may not actually have that resolution.  That is, I may schedule something to happen in 1</span></div>
<div class="line"><a id="l00149" name="l00149"></a><span class="lineno">  149</span><span class="comment"> * millisecond and then measure the time passed, using a high-res clock like #Fine_clock, and discover that</span></div>
<div class="line"><a id="l00150" name="l00150"></a><span class="lineno">  150</span><span class="comment"> * the wait was actually 15 milliseconds.  This is not a problem for most timers.  (In Flow itself, the most advanced</span></div>
<div class="line"><a id="l00151" name="l00151"></a><span class="lineno">  151</span><span class="comment"> * use of timers by far is in flow::net_flow.  Timers used in flow::net_flow -- delayed ACK timer, Drop Timer, simulated</span></div>
<div class="line"><a id="l00152" name="l00152"></a><span class="lineno">  152</span><span class="comment"> * latency timer -- typically are for `n x 50` milliseconds time periods or coarser.)  However that may not be the</span></div>
<div class="line"><a id="l00153" name="l00153"></a><span class="lineno">  153</span><span class="comment"> * case for all timers.  (In particular, flow::net_flow packet pacing may use finer time periods.)</span></div>
<div class="line"><a id="l00154" name="l00154"></a><span class="lineno">  154</span><span class="comment"> *</span></div>
<div class="line"><a id="l00155" name="l00155"></a><span class="lineno">  155</span><span class="comment"> * @note The flow::net_flow references in the present doc header speak of internal implementation details -- not</span></div>
<div class="line"><a id="l00156" name="l00156"></a><span class="lineno">  156</span><span class="comment"> *       of interest to the `net_flow` *user*.  I leave them in this public doc header for practical purposes, as</span></div>
<div class="line"><a id="l00157" name="l00157"></a><span class="lineno">  157</span><span class="comment"> *       examples needed to discuss some Inside-Baseball topics involved.</span></div>
<div class="line"><a id="l00158" name="l00158"></a><span class="lineno">  158</span><span class="comment"> *</span></div>
<div class="line"><a id="l00159" name="l00159"></a><span class="lineno">  159</span><span class="comment"> * So I looked into what boost.asio provides.  `deadline_timer` uses the system clock</span></div>
<div class="line"><a id="l00160" name="l00160"></a><span class="lineno">  160</span><span class="comment"> * (`universal_time()`) as the time reference, while `basic_waitable_timer&lt;Fine_clock&gt;` uses the</span></div>
<div class="line"><a id="l00161" name="l00161"></a><span class="lineno">  161</span><span class="comment"> * high-resolution clock (see #Fine_clock).  I tested both (using `wait()`s of various lengths</span></div>
<div class="line"><a id="l00162" name="l00162"></a><span class="lineno">  162</span><span class="comment"> * and using #Fine_clock to measure duration) and observed the following resolutions on certain OS</span></div>
<div class="line"><a id="l00163" name="l00163"></a><span class="lineno">  163</span><span class="comment"> * (not listing the hardware):</span></div>
<div class="line"><a id="l00164" name="l00164"></a><span class="lineno">  164</span><span class="comment"> *</span></div>
<div class="line"><a id="l00165" name="l00165"></a><span class="lineno">  165</span><span class="comment"> *   - Linux (2.6.x kernel): sub-2 millisecond resolution, with some variance.</span></div>
<div class="line"><a id="l00166" name="l00166"></a><span class="lineno">  166</span><span class="comment"> *     (Note: This Linux&#39;s `glibc` is too old to provide the `timerfd` API, therefore Boost falls back to</span></div>
<div class="line"><a id="l00167" name="l00167"></a><span class="lineno">  167</span><span class="comment"> *     using `epoll_wait()` directly; on a newer Linux this may get better results.)</span></div>
<div class="line"><a id="l00168" name="l00168"></a><span class="lineno">  168</span><span class="comment"> *   - Windows 7: 15 millisecond resolution, with little variance.</span></div>
<div class="line"><a id="l00169" name="l00169"></a><span class="lineno">  169</span><span class="comment"> *   - macOS: untested.  @todo Test macOS timer fidelity.</span></div>
<div class="line"><a id="l00170" name="l00170"></a><span class="lineno">  170</span><span class="comment"> *</span></div>
<div class="line"><a id="l00171" name="l00171"></a><span class="lineno">  171</span><span class="comment"> * These results were observed for BOTH `deadline_timer` and `basic_waitable_timer&lt;Fine_clock&gt;`</span></div>
<div class="line"><a id="l00172" name="l00172"></a><span class="lineno">  172</span><span class="comment"> * in Boost 1.50.  Thus, there was no resolution advantage to using the latter -- only an interface advantage.</span></div>
<div class="line"><a id="l00173" name="l00173"></a><span class="lineno">  173</span><span class="comment"> * Conclusion: we&#39;d be well-advised not to rely on anything much smaller than 20 milliseconds when</span></div>
<div class="line"><a id="l00174" name="l00174"></a><span class="lineno">  174</span><span class="comment"> * scheduling timer events.  One technique might be, given any time T &lt; 20 ms, to assume T = 0</span></div>
<div class="line"><a id="l00175" name="l00175"></a><span class="lineno">  175</span><span class="comment"> * (i.e., execute immediately).  This may or may not be appropriate depending on the situation.</span></div>
<div class="line"><a id="l00176" name="l00176"></a><span class="lineno">  176</span><span class="comment"> *</span></div>
<div class="line"><a id="l00177" name="l00177"></a><span class="lineno">  177</span><span class="comment"> * However, using `basic_waitable_timer&lt;Fine_clock&gt;` may get an additional nice property: #Fine_clock</span></div>
<div class="line"><a id="l00178" name="l00178"></a><span class="lineno">  178</span><span class="comment"> * always goes forward and cannot be affected by NTP or user changes.  `deadline_timer` may or may not</span></div>
<div class="line"><a id="l00179" name="l00179"></a><span class="lineno">  179</span><span class="comment"> * be affected by such tomfoolery (untested, but the potential is clearly there).  Therefore we do the best</span></div>
<div class="line"><a id="l00180" name="l00180"></a><span class="lineno">  180</span><span class="comment"> * we can by using the #Fine_clock-based timer.</span></div>
<div class="line"><a id="l00181" name="l00181"></a><span class="lineno">  181</span><span class="comment"> *</span></div>
<div class="line"><a id="l00182" name="l00182"></a><span class="lineno">  182</span><span class="comment"> * @todo Upgrade to newer Boost and keep testing timer resolutions on the above and other OS versions.</span></div>
<div class="line"><a id="l00183" name="l00183"></a><span class="lineno">  183</span><span class="comment"> * Update: As of this writing we are on Boost 1.74 now.  Needless to say, it is time to reassess the above, as it</span></div>
<div class="line"><a id="l00184" name="l00184"></a><span class="lineno">  184</span><span class="comment"> * has been years since 1.50 -- and we had been on 1.63 and 1.66 for long period of time, let alone 1.74.</span></div>
<div class="line"><a id="l00185" name="l00185"></a><span class="lineno">  185</span><span class="comment"> * Update: No changes with Boost 1.75, the newest version as of this writing.</span></div>
<div class="line"><a id="l00186" name="l00186"></a><span class="lineno">  186</span><span class="comment"> *</span></div>
<div class="line"><a id="l00187" name="l00187"></a><span class="lineno">  187</span><span class="comment"> * @note One annoying, though fully documented, &quot;feature&quot; of this and all boost.asio timers is that `cancel()`ing it</span></div>
<div class="line"><a id="l00188" name="l00188"></a><span class="lineno">  188</span><span class="comment"> * does not always cause the handler to fire with `operation_aborted` error code.  Sometimes it was already &quot;just</span></div>
<div class="line"><a id="l00189" name="l00189"></a><span class="lineno">  189</span><span class="comment"> * about&quot; to fire at `cancel()` time, so the handler will run with no error code regardless of the `cancel()`.</span></div>
<div class="line"><a id="l00190" name="l00190"></a><span class="lineno">  190</span><span class="comment"> * Personally I have never once found this behavior useful, and there is much code currently written to work</span></div>
<div class="line"><a id="l00191" name="l00191"></a><span class="lineno">  191</span><span class="comment"> * around this &quot;feature.&quot;  Furthermore, even a &quot;successful&quot; cancel still runs the handler but with `operation_aborted`;</span></div>
<div class="line"><a id="l00192" name="l00192"></a><span class="lineno">  192</span><span class="comment"> * 99.999% of the time one would want to just not run it at all.  Finally, in many cases, even having to create</span></div>
<div class="line"><a id="l00193" name="l00193"></a><span class="lineno">  193</span><span class="comment"> * a timer object (and then the multiple steps required to actually schedule a thing) feels like more boiler-plate</span></div>
<div class="line"><a id="l00194" name="l00194"></a><span class="lineno">  194</span><span class="comment"> * than should be necessary.  To avoid all of these usability issues, see schedule_task_from_now() (and similar),</span></div>
<div class="line"><a id="l00195" name="l00195"></a><span class="lineno">  195</span><span class="comment"> * which is a facility that wraps `Timer` for a boiler-plate-free experience sufficient in the majority of practical</span></div>
<div class="line"><a id="l00196" name="l00196"></a><span class="lineno">  196</span><span class="comment"> * situations.  `Timer` is to be used directly when that simpler facility is insufficient.</span></div>
<div class="line"><a id="l00197" name="l00197"></a><span class="lineno">  197</span><span class="comment"> *</span></div>
<div class="line"><a id="l00198" name="l00198"></a><span class="lineno">  198</span><span class="comment"> * @note `b_w_t&lt;Fine_clock&gt;` happens to equal `boost::asio::high_resolution_timer`. We chose to alias</span></div>
<div class="line"><a id="l00199" name="l00199"></a><span class="lineno">  199</span><span class="comment"> *       in terms of #Fine_clock merely to ensure that #Fine_duration is one-to-one compatible with it, as it</span></div>
<div class="line"><a id="l00200" name="l00200"></a><span class="lineno">  200</span><span class="comment"> *       is defined in terms of #Fine_clock also.</span></div>
<div class="line"><a id="l00201" name="l00201"></a><span class="lineno">  201</span><span class="comment"> */</span></div>
<div class="line"><a id="l00202" name="l00202"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#ae7416d64d2989051104bb396e28e15e6">  202</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#ae7416d64d2989051104bb396e28e15e6">Timer</a> = boost::asio::basic_waitable_timer&lt;Fine_clock&gt;;</div>
<div class="line"><a id="l00203" name="l00203"></a><span class="lineno">  203</span><span class="comment"></span> </div>
<div class="line"><a id="l00204" name="l00204"></a><span class="lineno">  204</span><span class="comment">/// Helper type for setup_auto_cleanup().</span></div>
<div class="line"><a id="l00205" name="l00205"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#ab22fd89e165a9e6deaa174bc0dfdc8de">  205</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#ab22fd89e165a9e6deaa174bc0dfdc8de">Auto_cleanup</a> = boost::shared_ptr&lt;void&gt;;</div>
<div class="line"><a id="l00206" name="l00206"></a><span class="lineno">  206</span><span class="comment"></span> </div>
<div class="line"><a id="l00207" name="l00207"></a><span class="lineno">  207</span><span class="comment">/// Short-hand for the UDP endpoint (IP/port) type.</span></div>
<div class="line"><a id="l00208" name="l00208"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#af1b28edb7bad743c1c77f6b982cc3196">  208</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#af1b28edb7bad743c1c77f6b982cc3196">Udp_endpoint</a> = boost::asio::ip::udp::endpoint;<span class="comment"></span></div>
<div class="line"><a id="l00209" name="l00209"></a><span class="lineno">  209</span><span class="comment">/// Short-hand for the IPv4 address type.</span></div>
<div class="line"><a id="l00210" name="l00210"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a331b3b73d9d633101d6f0ebc1c829701">  210</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a331b3b73d9d633101d6f0ebc1c829701">Ip_address_v4</a> = boost::asio::ip::address_v4;<span class="comment"></span></div>
<div class="line"><a id="l00211" name="l00211"></a><span class="lineno">  211</span><span class="comment">/// Short-hand for the IPv6 address type.</span></div>
<div class="line"><a id="l00212" name="l00212"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a2ed0f6ab85f5df463bb10913b0764540">  212</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a2ed0f6ab85f5df463bb10913b0764540">Ip_address_v6</a> = boost::asio::ip::address_v6;</div>
<div class="line"><a id="l00213" name="l00213"></a><span class="lineno">  213</span><span class="comment"></span> </div>
<div class="line"><a id="l00214" name="l00214"></a><span class="lineno">  214</span><span class="comment">/// Short-hand for non-reentrant, exclusive mutex.  (&quot;Reentrant&quot; = one can lock an already-locked-in-that-thread mutex.)</span></div>
<div class="line"><a id="l00215" name="l00215"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#add6ade273326f27eaf9bfd170a909626">  215</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#add6ade273326f27eaf9bfd170a909626">Mutex_non_recursive</a> = boost::mutex;</div>
<div class="line"><a id="l00216" name="l00216"></a><span class="lineno">  216</span><span class="comment"></span> </div>
<div class="line"><a id="l00217" name="l00217"></a><span class="lineno">  217</span><span class="comment">/// Short-hand for reentrant, exclusive mutex.</span></div>
<div class="line"><a id="l00218" name="l00218"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a9c7a5df07c2e86c788de9e6bbaee77d5">  218</a></span><span class="comment"></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a9c7a5df07c2e86c788de9e6bbaee77d5">Mutex_recursive</a> = boost::recursive_mutex;</div>
<div class="line"><a id="l00219" name="l00219"></a><span class="lineno">  219</span><span class="comment"></span> </div>
<div class="line"><a id="l00220" name="l00220"></a><span class="lineno">  220</span><span class="comment">/**</span></div>
<div class="line"><a id="l00221" name="l00221"></a><span class="lineno">  221</span><span class="comment"> * Short-hand for non-reentrant, shared-or-exclusive mutex.</span></div>
<div class="line"><a id="l00222" name="l00222"></a><span class="lineno">  222</span><span class="comment"> * When locking one of these, choose one of:</span></div>
<div class="line"><a id="l00223" name="l00223"></a><span class="lineno">  223</span><span class="comment"> * `Lock_guard&lt;Mutex_shared_non_recursive&gt;`, `Shared_lock_guard&lt;Mutex_shared_non_recursive&gt;`.</span></div>
<div class="line"><a id="l00224" name="l00224"></a><span class="lineno">  224</span><span class="comment"> * The level of locking acquired (shared vs. exclusive) depends on which you chose and is thus highly significant.</span></div>
<div class="line"><a id="l00225" name="l00225"></a><span class="lineno">  225</span><span class="comment"> *</span></div>
<div class="line"><a id="l00226" name="l00226"></a><span class="lineno">  226</span><span class="comment"> * @todo Consider changing util::Mutex_shared_non_recursive from `boost::shared_mutex` to `std::shared_mutex`, as</span></div>
<div class="line"><a id="l00227" name="l00227"></a><span class="lineno">  227</span><span class="comment"> * the former has a long-standing unresolved ticket about its impl being slow and/or outdated (as of Boost-1.80).</span></div>
<div class="line"><a id="l00228" name="l00228"></a><span class="lineno">  228</span><span class="comment"> * However see also the note on util::Mutex_shared_non_recursive that explains why it might be best to avoid</span></div>
<div class="line"><a id="l00229" name="l00229"></a><span class="lineno">  229</span><span class="comment"> * this type of mutex altogether in the first place (in most cases).</span></div>
<div class="line"><a id="l00230" name="l00230"></a><span class="lineno">  230</span><span class="comment"> *</span></div>
<div class="line"><a id="l00231" name="l00231"></a><span class="lineno">  231</span><span class="comment"> * ### When to use versus #Mutex_non_recursive ###</span></div>
<div class="line"><a id="l00232" name="l00232"></a><span class="lineno">  232</span><span class="comment"> * Experts suggest fairly strongly that one should be very wary about using a shared mutex, over a simple</span></div>
<div class="line"><a id="l00233" name="l00233"></a><span class="lineno">  233</span><span class="comment"> * non-recursive exclusive mutex, in almost any practical application.  The reason there&#39;s a trade-off at all is</span></div>
<div class="line"><a id="l00234" name="l00234"></a><span class="lineno">  234</span><span class="comment"> * that a #Mutex_non_recursive is extremely fast to lock and unlock; the entire perf cost is in waiting for</span></div>
<div class="line"><a id="l00235" name="l00235"></a><span class="lineno">  235</span><span class="comment"> * another thread to unlock first; so without contention it&#39;s almost *free*.  In contrast apparently any real</span></div>
<div class="line"><a id="l00236" name="l00236"></a><span class="lineno">  236</span><span class="comment"> * impl of #Mutex_shared_non_recursive is much slower to lock/unlock.  The trade-off is against allowing</span></div>
<div class="line"><a id="l00237" name="l00237"></a><span class="lineno">  237</span><span class="comment"> * reads to proceed in parallel; but experts say this is &quot;worth it&quot; only when these read critical sections</span></div>
<div class="line"><a id="l00238" name="l00238"></a><span class="lineno">  238</span><span class="comment"> * are lengthy and very frequently invoked.  So, for example, if the lock/unlock is around an `unordered_map`</span></div>
<div class="line"><a id="l00239" name="l00239"></a><span class="lineno">  239</span><span class="comment"> * lookup with a quick hashing function, it would be quite difficult to induce enough lock contention</span></div>
<div class="line"><a id="l00240" name="l00240"></a><span class="lineno">  240</span><span class="comment"> * to make a shared mutex better than an exclusive one.  (Note this is assuming even no perf issue with</span></div>
<div class="line"><a id="l00241" name="l00241"></a><span class="lineno">  241</span><span class="comment"> * `boost::shared_mutex` specifically.)</span></div>
<div class="line"><a id="l00242" name="l00242"></a><span class="lineno">  242</span><span class="comment"> */</span></div>
<div class="line"><a id="l00243" name="l00243"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a62b5ba6d6a549ac20e2c055e72bef421">  243</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a62b5ba6d6a549ac20e2c055e72bef421">Mutex_shared_non_recursive</a> = boost::shared_mutex;</div>
<div class="line"><a id="l00244" name="l00244"></a><span class="lineno">  244</span><span class="comment"></span> </div>
<div class="line"><a id="l00245" name="l00245"></a><span class="lineno">  245</span><span class="comment">/**</span></div>
<div class="line"><a id="l00246" name="l00246"></a><span class="lineno">  246</span><span class="comment"> * Short-hand for a mutex type equivalent to util::Mutex_shared_non_recursive -- except that the lock/unlock mutex ops</span></div>
<div class="line"><a id="l00247" name="l00247"></a><span class="lineno">  247</span><span class="comment"> * all do nothing.  One can parameterize templates accordingly; so that an algorithm can be generically written to work</span></div>
<div class="line"><a id="l00248" name="l00248"></a><span class="lineno">  248</span><span class="comment"> * in both single- and multi-threaded contexts without branching into 2 code paths, yet avoid the unnecessary actual</span></div>
<div class="line"><a id="l00249" name="l00249"></a><span class="lineno">  249</span><span class="comment"> * locking in the former case.</span></div>
<div class="line"><a id="l00250" name="l00250"></a><span class="lineno">  250</span><span class="comment"> */</span></div>
<div class="line"><a id="l00251" name="l00251"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#aeee121f0277371517fd2f5c3a20d8112">  251</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#aeee121f0277371517fd2f5c3a20d8112">Mutex_noop_shared_non_recursive</a> = boost::null_mutex;</div>
<div class="line"><a id="l00252" name="l00252"></a><span class="lineno">  252</span><span class="comment"></span> </div>
<div class="line"><a id="l00253" name="l00253"></a><span class="lineno">  253</span><span class="comment">/**</span></div>
<div class="line"><a id="l00254" name="l00254"></a><span class="lineno">  254</span><span class="comment"> * Short-hand for advanced-capability RAII lock guard for any mutex, ensuring exclusive ownership of that mutex.</span></div>
<div class="line"><a id="l00255" name="l00255"></a><span class="lineno">  255</span><span class="comment"> * Note the advanced API available for the underlying type: it is possible to relinquish ownership without unlocking,</span></div>
<div class="line"><a id="l00256" name="l00256"></a><span class="lineno">  256</span><span class="comment"> * gain ownership of a locked mutex; and so on.</span></div>
<div class="line"><a id="l00257" name="l00257"></a><span class="lineno">  257</span><span class="comment"> *</span></div>
<div class="line"><a id="l00258" name="l00258"></a><span class="lineno">  258</span><span class="comment"> * @see To grab shared-level ownership of a shared-or-exclusive mutex: use #Shared_lock_guard.</span></div>
<div class="line"><a id="l00259" name="l00259"></a><span class="lineno">  259</span><span class="comment"> *</span></div>
<div class="line"><a id="l00260" name="l00260"></a><span class="lineno">  260</span><span class="comment"> * @tparam Mutex</span></div>
<div class="line"><a id="l00261" name="l00261"></a><span class="lineno">  261</span><span class="comment"> *         A non-recursive or recursive mutex type.  Recommend one of:</span></div>
<div class="line"><a id="l00262" name="l00262"></a><span class="lineno">  262</span><span class="comment"> *         #Mutex_non_recursive, #Mutex_recursive, #Mutex_shared_non_recursive, #Mutex_noop_shared_non_recursive.</span></div>
<div class="line"><a id="l00263" name="l00263"></a><span class="lineno">  263</span><span class="comment"> */</span></div>
<div class="line"><a id="l00264" name="l00264"></a><span class="lineno">  264</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Mutex&gt;</div>
<div class="line"><a id="l00265" name="l00265"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a5d2247b715da63e4b960909561b90ae7">  265</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a5d2247b715da63e4b960909561b90ae7">Lock_guard</a> = boost::unique_lock&lt;Mutex&gt;;</div>
<div class="line"><a id="l00266" name="l00266"></a><span class="lineno">  266</span><span class="comment"></span> </div>
<div class="line"><a id="l00267" name="l00267"></a><span class="lineno">  267</span><span class="comment">/**</span></div>
<div class="line"><a id="l00268" name="l00268"></a><span class="lineno">  268</span><span class="comment"> * Short-hand for *shared mode* advanced-capability RAII lock guard, particuarly for #Mutex_shared_non_recursive</span></div>
<div class="line"><a id="l00269" name="l00269"></a><span class="lineno">  269</span><span class="comment"> * mutexes.</span></div>
<div class="line"><a id="l00270" name="l00270"></a><span class="lineno">  270</span><span class="comment"> *</span></div>
<div class="line"><a id="l00271" name="l00271"></a><span class="lineno">  271</span><span class="comment"> * @tparam Shared_mutex</span></div>
<div class="line"><a id="l00272" name="l00272"></a><span class="lineno">  272</span><span class="comment"> *         Typically #Mutex_shared_non_recursive, but any mutex type with that both-exclusive-and-shared API will work.</span></div>
<div class="line"><a id="l00273" name="l00273"></a><span class="lineno">  273</span><span class="comment"> */</span></div>
<div class="line"><a id="l00274" name="l00274"></a><span class="lineno">  274</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Shared_mutex&gt;</div>
<div class="line"><a id="l00275" name="l00275"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#ac4f0492f15f46f70581feac50b9217ee">  275</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#ac4f0492f15f46f70581feac50b9217ee">Shared_lock_guard</a> = boost::shared_lock&lt;Shared_mutex&gt;;</div>
<div class="line"><a id="l00276" name="l00276"></a><span class="lineno">  276</span><span class="comment"></span> </div>
<div class="line"><a id="l00277" name="l00277"></a><span class="lineno">  277</span><span class="comment">/**</span></div>
<div class="line"><a id="l00278" name="l00278"></a><span class="lineno">  278</span><span class="comment"> * (Deprecated given C++1x) Short-hand for advanced-capability RAII lock guard for #Mutex_non_recursive mutexes.</span></div>
<div class="line"><a id="l00279" name="l00279"></a><span class="lineno">  279</span><span class="comment"> *</span></div>
<div class="line"><a id="l00280" name="l00280"></a><span class="lineno">  280</span><span class="comment"> * @todo #Lock_guard_non_recursive is deprecated, now that C++1x made the more flexible</span></div>
<div class="line"><a id="l00281" name="l00281"></a><span class="lineno">  281</span><span class="comment"> * `Lock_guard&lt;Mutex_non_recursive&gt;` possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00282" name="l00282"></a><span class="lineno">  282</span><span class="comment"> */</span></div>
<div class="line"><a id="l00283" name="l00283"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a9495b3e37e9d27bcc7767a4b6ce87ff4">  283</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a9495b3e37e9d27bcc7767a4b6ce87ff4">Lock_guard_non_recursive</a> = boost::unique_lock&lt;Mutex_non_recursive&gt;;</div>
<div class="line"><a id="l00284" name="l00284"></a><span class="lineno">  284</span><span class="comment"></span> </div>
<div class="line"><a id="l00285" name="l00285"></a><span class="lineno">  285</span><span class="comment">/**</span></div>
<div class="line"><a id="l00286" name="l00286"></a><span class="lineno">  286</span><span class="comment"> * (Deprecated given C++1x) Short-hand for advanced-capability RAII lock guard for #Mutex_recursive mutexes.</span></div>
<div class="line"><a id="l00287" name="l00287"></a><span class="lineno">  287</span><span class="comment"> *</span></div>
<div class="line"><a id="l00288" name="l00288"></a><span class="lineno">  288</span><span class="comment"> * @todo #Lock_guard_recursive is deprecated, now that C++1x made the more flexible `Lock_guard&lt;Mutex_recursive&gt;`</span></div>
<div class="line"><a id="l00289" name="l00289"></a><span class="lineno">  289</span><span class="comment"> * possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00290" name="l00290"></a><span class="lineno">  290</span><span class="comment"> */</span></div>
<div class="line"><a id="l00291" name="l00291"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a015b84cfa3076b8e75d16ec44a5514a3">  291</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a015b84cfa3076b8e75d16ec44a5514a3">Lock_guard_recursive</a> = boost::unique_lock&lt;Mutex_recursive&gt;;</div>
<div class="line"><a id="l00292" name="l00292"></a><span class="lineno">  292</span><span class="comment"></span> </div>
<div class="line"><a id="l00293" name="l00293"></a><span class="lineno">  293</span><span class="comment">/**</span></div>
<div class="line"><a id="l00294" name="l00294"></a><span class="lineno">  294</span><span class="comment"> * (Deprecated given C++1x) Short-hand for *shared mode* advanced-capability RAII lock guard for</span></div>
<div class="line"><a id="l00295" name="l00295"></a><span class="lineno">  295</span><span class="comment"> * #Mutex_shared_non_recursive mutexes.</span></div>
<div class="line"><a id="l00296" name="l00296"></a><span class="lineno">  296</span><span class="comment"> *</span></div>
<div class="line"><a id="l00297" name="l00297"></a><span class="lineno">  297</span><span class="comment"> * @todo #Lock_guard_shared_non_recursive_sh is deprecated, now that C++1x made the more flexible</span></div>
<div class="line"><a id="l00298" name="l00298"></a><span class="lineno">  298</span><span class="comment"> * `Shared_lock_guard&lt;Mutex_shared_non_recursive&gt;` possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00299" name="l00299"></a><span class="lineno">  299</span><span class="comment"> */</span></div>
<div class="line"><a id="l00300" name="l00300"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a689388b6eb7e760933d99381d65cacca">  300</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a689388b6eb7e760933d99381d65cacca">Lock_guard_shared_non_recursive_sh</a> = boost::shared_lock&lt;Mutex_shared_non_recursive&gt;;</div>
<div class="line"><a id="l00301" name="l00301"></a><span class="lineno">  301</span><span class="comment"></span> </div>
<div class="line"><a id="l00302" name="l00302"></a><span class="lineno">  302</span><span class="comment">/**</span></div>
<div class="line"><a id="l00303" name="l00303"></a><span class="lineno">  303</span><span class="comment"> * (Deprecated given C++1x) Short-hand for *exclusive mode* advanced-capability RAII lock guard for</span></div>
<div class="line"><a id="l00304" name="l00304"></a><span class="lineno">  304</span><span class="comment"> * #Mutex_shared_non_recursive mutexes.</span></div>
<div class="line"><a id="l00305" name="l00305"></a><span class="lineno">  305</span><span class="comment"> *</span></div>
<div class="line"><a id="l00306" name="l00306"></a><span class="lineno">  306</span><span class="comment"> * @todo #Lock_guard_shared_non_recursive_ex is deprecated, now that C++1x made the more flexible</span></div>
<div class="line"><a id="l00307" name="l00307"></a><span class="lineno">  307</span><span class="comment"> * `Lock_guard&lt;Mutex_shared_non_recursive&gt;` possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00308" name="l00308"></a><span class="lineno">  308</span><span class="comment"> */</span></div>
<div class="line"><a id="l00309" name="l00309"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a9df3cc2f3aec0c0353443b9d6c81e638">  309</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a9df3cc2f3aec0c0353443b9d6c81e638">Lock_guard_shared_non_recursive_ex</a> = boost::unique_lock&lt;Mutex_shared_non_recursive&gt;;</div>
<div class="line"><a id="l00310" name="l00310"></a><span class="lineno">  310</span><span class="comment"></span> </div>
<div class="line"><a id="l00311" name="l00311"></a><span class="lineno">  311</span><span class="comment">/**</span></div>
<div class="line"><a id="l00312" name="l00312"></a><span class="lineno">  312</span><span class="comment"> * (Deprecated given C++1x) Equivalent to #Lock_guard_shared_non_recursive_sh but applied to</span></div>
<div class="line"><a id="l00313" name="l00313"></a><span class="lineno">  313</span><span class="comment"> * #Mutex_noop_shared_non_recursive.</span></div>
<div class="line"><a id="l00314" name="l00314"></a><span class="lineno">  314</span><span class="comment"> *</span></div>
<div class="line"><a id="l00315" name="l00315"></a><span class="lineno">  315</span><span class="comment"> * @todo #Lock_guard_noop_shared_non_recursive_sh is deprecated, now that C++1x made the more flexible</span></div>
<div class="line"><a id="l00316" name="l00316"></a><span class="lineno">  316</span><span class="comment"> * `Shared_lock_guard&lt;Mutex_noop_shared_non_recursive&gt;` possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00317" name="l00317"></a><span class="lineno">  317</span><span class="comment"> */</span></div>
<div class="line"><a id="l00318" name="l00318"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#a9e5fae573be960434c4c9dacd48c9c11">  318</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#a9e5fae573be960434c4c9dacd48c9c11">Lock_guard_noop_shared_non_recursive_sh</a> = boost::shared_lock&lt;Mutex_noop_shared_non_recursive&gt;;</div>
<div class="line"><a id="l00319" name="l00319"></a><span class="lineno">  319</span><span class="comment"></span> </div>
<div class="line"><a id="l00320" name="l00320"></a><span class="lineno">  320</span><span class="comment">/**</span></div>
<div class="line"><a id="l00321" name="l00321"></a><span class="lineno">  321</span><span class="comment"> * (Deprecated given C++1x) Equivalent to #Lock_guard_shared_non_recursive_ex but applied to</span></div>
<div class="line"><a id="l00322" name="l00322"></a><span class="lineno">  322</span><span class="comment"> * #Mutex_noop_shared_non_recursive.</span></div>
<div class="line"><a id="l00323" name="l00323"></a><span class="lineno">  323</span><span class="comment"> *</span></div>
<div class="line"><a id="l00324" name="l00324"></a><span class="lineno">  324</span><span class="comment"> * @todo #Lock_guard_noop_shared_non_recursive_ex is deprecated, now that C++1x made the more flexible</span></div>
<div class="line"><a id="l00325" name="l00325"></a><span class="lineno">  325</span><span class="comment"> * `Lock_guard&lt;Mutex_noop_shared_non_recursive&gt;` possible.  Remove it and all (outside) uses eventually.</span></div>
<div class="line"><a id="l00326" name="l00326"></a><span class="lineno">  326</span><span class="comment"> */</span></div>
<div class="line"><a id="l00327" name="l00327"></a><span class="lineno"><a class="line" href="namespaceflow_1_1util.html#add56211dee74c212c19028f1ded2a785">  327</a></span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow_1_1util.html#add56211dee74c212c19028f1ded2a785">Lock_guard_noop_shared_non_recursive_ex</a> = boost::unique_lock&lt;Mutex_noop_shared_non_recursive&gt;;</div>
<div class="line"><a id="l00328" name="l00328"></a><span class="lineno">  328</span> </div>
<div class="line"><a id="l00329" name="l00329"></a><span class="lineno">  329</span><span class="comment">// Free functions.</span></div>
<div class="line"><a id="l00330" name="l00330"></a><span class="lineno">  330</span><span class="comment"></span> </div>
<div class="line"><a id="l00331" name="l00331"></a><span class="lineno">  331</span><span class="comment">/**</span></div>
<div class="line"><a id="l00332" name="l00332"></a><span class="lineno">  332</span><span class="comment"> * Equivalent to `val1.swap(val2)`.</span></div>
<div class="line"><a id="l00333" name="l00333"></a><span class="lineno">  333</span><span class="comment"> *</span></div>
<div class="line"><a id="l00334" name="l00334"></a><span class="lineno">  334</span><span class="comment"> * @relatesalso Linked_hash_map</span></div>
<div class="line"><a id="l00335" name="l00335"></a><span class="lineno">  335</span><span class="comment"> * @param val1</span></div>
<div class="line"><a id="l00336" name="l00336"></a><span class="lineno">  336</span><span class="comment"> *        Object.</span></div>
<div class="line"><a id="l00337" name="l00337"></a><span class="lineno">  337</span><span class="comment"> * @param val2</span></div>
<div class="line"><a id="l00338" name="l00338"></a><span class="lineno">  338</span><span class="comment"> *        Object.</span></div>
<div class="line"><a id="l00339" name="l00339"></a><span class="lineno">  339</span><span class="comment"> */</span></div>
<div class="line"><a id="l00340" name="l00340"></a><span class="lineno">  340</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Key, <span class="keyword">typename</span> Mapped, <span class="keyword">typename</span> Hash, <span class="keyword">typename</span> Pred&gt;</div>
<div class="line"><a id="l00341" name="l00341"></a><span class="lineno">  341</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a71eaa4ab6a2673ed34fa8989c47a7bc0">swap</a>(<a class="code hl_class" href="classflow_1_1util_1_1Linked__hash__map.html">Linked_hash_map&lt;Key, Mapped, Hash, Pred&gt;</a>&amp; val1, <a class="code hl_class" href="classflow_1_1util_1_1Linked__hash__map.html">Linked_hash_map&lt;Key, Mapped, Hash, Pred&gt;</a>&amp; val2);</div>
<div class="line"><a id="l00342" name="l00342"></a><span class="lineno">  342</span><span class="comment"></span> </div>
<div class="line"><a id="l00343" name="l00343"></a><span class="lineno">  343</span><span class="comment">/**</span></div>
<div class="line"><a id="l00344" name="l00344"></a><span class="lineno">  344</span><span class="comment"> * Equivalent to `val1.swap(val2)`.</span></div>
<div class="line"><a id="l00345" name="l00345"></a><span class="lineno">  345</span><span class="comment"> *</span></div>
<div class="line"><a id="l00346" name="l00346"></a><span class="lineno">  346</span><span class="comment"> * @relatesalso Linked_hash_set</span></div>
<div class="line"><a id="l00347" name="l00347"></a><span class="lineno">  347</span><span class="comment"> * @param val1</span></div>
<div class="line"><a id="l00348" name="l00348"></a><span class="lineno">  348</span><span class="comment"> *        Object.</span></div>
<div class="line"><a id="l00349" name="l00349"></a><span class="lineno">  349</span><span class="comment"> * @param val2</span></div>
<div class="line"><a id="l00350" name="l00350"></a><span class="lineno">  350</span><span class="comment"> *        Object.</span></div>
<div class="line"><a id="l00351" name="l00351"></a><span class="lineno">  351</span><span class="comment"> */</span></div>
<div class="line"><a id="l00352" name="l00352"></a><span class="lineno">  352</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Key, <span class="keyword">typename</span> Hash, <span class="keyword">typename</span> Pred&gt;</div>
<div class="line"><a id="l00353" name="l00353"></a><span class="lineno">  353</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a71eaa4ab6a2673ed34fa8989c47a7bc0">swap</a>(<a class="code hl_class" href="classflow_1_1util_1_1Linked__hash__set.html">Linked_hash_set&lt;Key, Hash, Pred&gt;</a>&amp; val1, <a class="code hl_class" href="classflow_1_1util_1_1Linked__hash__set.html">Linked_hash_set&lt;Key, Hash, Pred&gt;</a>&amp; val2);</div>
<div class="line"><a id="l00354" name="l00354"></a><span class="lineno">  354</span><span class="comment"></span> </div>
<div class="line"><a id="l00355" name="l00355"></a><span class="lineno">  355</span><span class="comment">/**</span></div>
<div class="line"><a id="l00356" name="l00356"></a><span class="lineno">  356</span><span class="comment"> * Get the current POSIX (Unix) time as a duration from the Epoch time point.</span></div>
<div class="line"><a id="l00357" name="l00357"></a><span class="lineno">  357</span><span class="comment"> *</span></div>
<div class="line"><a id="l00358" name="l00358"></a><span class="lineno">  358</span><span class="comment"> * This is the amount of time -- according to the user-settable system clock time -- to have passed since the</span></div>
<div class="line"><a id="l00359" name="l00359"></a><span class="lineno">  359</span><span class="comment"> * POSIX (Unix) Epoch -- January 1st, 1970, 00:00:00 UTC -- not counting leap seconds to have been inserted or deleted</span></div>
<div class="line"><a id="l00360" name="l00360"></a><span class="lineno">  360</span><span class="comment"> * between then and now.</span></div>
<div class="line"><a id="l00361" name="l00361"></a><span class="lineno">  361</span><span class="comment"> *</span></div>
<div class="line"><a id="l00362" name="l00362"></a><span class="lineno">  362</span><span class="comment"> * The `boost::chrono` duration type is chosen so as to support the entire supported resolution of the</span></div>
<div class="line"><a id="l00363" name="l00363"></a><span class="lineno">  363</span><span class="comment"> * OS-exposed system clock (but probably no more than that).</span></div>
<div class="line"><a id="l00364" name="l00364"></a><span class="lineno">  364</span><span class="comment"> *</span></div>
<div class="line"><a id="l00365" name="l00365"></a><span class="lineno">  365</span><span class="comment"> * ### Known use cases, alternatives ###</span></div>
<div class="line"><a id="l00366" name="l00366"></a><span class="lineno">  366</span><span class="comment"> * - Logging of time stamps.  Output the raw value; or use boost.locale to output `ceil&lt;seconds&gt;()` in the desired</span></div>
<div class="line"><a id="l00367" name="l00367"></a><span class="lineno">  367</span><span class="comment"> *   human-friendly form, splicing in the left-over microseconds where desired (boost.locale lacks formatters for</span></div>
<div class="line"><a id="l00368" name="l00368"></a><span class="lineno">  368</span><span class="comment"> *   sub-second-resolution time points).  However see below for a typically-superior alternative.</span></div>
<div class="line"><a id="l00369" name="l00369"></a><span class="lineno">  369</span><span class="comment"> * - By subtracting return values of this at various points in time from each other, as a crude timing mechanism.</span></div>
<div class="line"><a id="l00370" name="l00370"></a><span class="lineno">  370</span><span class="comment"> *   (Various considerations make it just that -- crude -- and best replaced by flow::Fine_clock and the like.</span></div>
<div class="line"><a id="l00371" name="l00371"></a><span class="lineno">  371</span><span class="comment"> *   Moreover see flow::perf::Checkpointing_timer.)</span></div>
<div class="line"><a id="l00372" name="l00372"></a><span class="lineno">  372</span><span class="comment"> * - It&#39;s a decent quick-and-dirty random seed.</span></div>
<div class="line"><a id="l00373" name="l00373"></a><span class="lineno">  373</span><span class="comment"> *</span></div>
<div class="line"><a id="l00374" name="l00374"></a><span class="lineno">  374</span><span class="comment"> * ### Update/subtleties re. time stamp output ###</span></div>
<div class="line"><a id="l00375" name="l00375"></a><span class="lineno">  375</span><span class="comment"> * Using this for time stamp output is no longer needed or convenient, as a much nicer way presents itself</span></div>
<div class="line"><a id="l00376" name="l00376"></a><span class="lineno">  376</span><span class="comment"> * when combined with boost.chrono I/O-v2 `time_point`-outputting `ostream&lt;&lt;` overload.  Just grab `time_point`</span></div>
<div class="line"><a id="l00377" name="l00377"></a><span class="lineno">  377</span><span class="comment"> * `boost::chrono::system_clock::now()` (or another `system_clock`-originated value); its default-formatted</span></div>
<div class="line"><a id="l00378" name="l00378"></a><span class="lineno">  378</span><span class="comment"> * `ostream&lt;&lt;` output will include date, time with microsecond+ precision, and time-zone specifier (one can choose</span></div>
<div class="line"><a id="l00379" name="l00379"></a><span class="lineno">  379</span><span class="comment"> * UTC or local time).</span></div>
<div class="line"><a id="l00380" name="l00380"></a><span class="lineno">  380</span><span class="comment"> *</span></div>
<div class="line"><a id="l00381" name="l00381"></a><span class="lineno">  381</span><span class="comment"> * However, as of this writing, it is not possible to directly obtain *just* the microsecond+</span></div>
<div class="line"><a id="l00382" name="l00382"></a><span class="lineno">  382</span><span class="comment"> * part of this, in isolation, according boost.chrono docs.  (One could hack it by taking a substring.)</span></div>
<div class="line"><a id="l00383" name="l00383"></a><span class="lineno">  383</span><span class="comment"> * Quote: &quot;Unfortunately there are no formatting/parsing sequences which indicate fractional seconds.&quot; From:</span></div>
<div class="line"><a id="l00384" name="l00384"></a><span class="lineno">  384</span><span class="comment"> * https://www.boost.org/doc/libs/1_76_0/doc/html/chrono/users_guide.html#chrono.users_guide.tutorial.i_o.system_clock_time_point_io)</span></div>
<div class="line"><a id="l00385" name="l00385"></a><span class="lineno">  385</span><span class="comment"> *</span></div>
<div class="line"><a id="l00386" name="l00386"></a><span class="lineno">  386</span><span class="comment"> * @return A duration representing how much time has passed since the Epoch reference point</span></div>
<div class="line"><a id="l00387" name="l00387"></a><span class="lineno">  387</span><span class="comment"> *         (could be negative if before it).</span></div>
<div class="line"><a id="l00388" name="l00388"></a><span class="lineno">  388</span><span class="comment"> */</span></div>
<div class="line"><a id="l00389" name="l00389"></a><span class="lineno">  389</span>boost::chrono::microseconds <a class="code hl_function" href="namespaceflow_1_1util.html#ad92ad411feccf73908abe6ed130d48f5">time_since_posix_epoch</a>();</div>
<div class="line"><a id="l00390" name="l00390"></a><span class="lineno">  390</span><span class="comment"></span> </div>
<div class="line"><a id="l00391" name="l00391"></a><span class="lineno">  391</span><span class="comment">/**</span></div>
<div class="line"><a id="l00392" name="l00392"></a><span class="lineno">  392</span><span class="comment"> * Writes a multi- or single-line string representation of the provided binary data to an output stream, complete with</span></div>
<div class="line"><a id="l00393" name="l00393"></a><span class="lineno">  393</span><span class="comment"> * a printable and hex versions of each byte.</span></div>
<div class="line"><a id="l00394" name="l00394"></a><span class="lineno">  394</span><span class="comment"> *   - Single-line mode is chosen by setting `bytes_per_line` to special value `-1`.  In this mode, the output</span></div>
<div class="line"><a id="l00395" name="l00395"></a><span class="lineno">  395</span><span class="comment"> *     consists of `indentation`, followed by a pretty-printed hex dump of every byte in `data` (no matter how many),</span></div>
<div class="line"><a id="l00396" name="l00396"></a><span class="lineno">  396</span><span class="comment"> *     followed by a pretty-printed ASCII-printable (or &#39;.&#39; if not so printable) character for each byte; that&#39;s it.</span></div>
<div class="line"><a id="l00397" name="l00397"></a><span class="lineno">  397</span><span class="comment"> *     No newline is added, and `indentation` is included only the one time.  It is recommended to therefore print</span></div>
<div class="line"><a id="l00398" name="l00398"></a><span class="lineno">  398</span><span class="comment"> *     &quot;in-line&quot; inside log messages (etc.) without surrounding newlines, etc., when using this mode.</span></div>
<div class="line"><a id="l00399" name="l00399"></a><span class="lineno">  399</span><span class="comment"> *   - Multi-line mode is chosen by setting `bytes_per_line` to a positive value; or 0 which auto-selects a decent</span></div>
<div class="line"><a id="l00400" name="l00400"></a><span class="lineno">  400</span><span class="comment"> *     default positive value.  Then, each line represents up to that many bytes, which are pretty-printed similarly</span></div>
<div class="line"><a id="l00401" name="l00401"></a><span class="lineno">  401</span><span class="comment"> *     to single-line mode, in order of appearance in `data` (with the last such line representing the last few bytes,</span></div>
<div class="line"><a id="l00402" name="l00402"></a><span class="lineno">  402</span><span class="comment"> *     formatting nicely including accounting for potentially fewer than the desired # of bytes per line).</span></div>
<div class="line"><a id="l00403" name="l00403"></a><span class="lineno">  403</span><span class="comment"> *     Every line starts with `indentation` and ends with a newline -- including the last line.</span></div>
<div class="line"><a id="l00404" name="l00404"></a><span class="lineno">  404</span><span class="comment"> *     Therefore, it is recommended to precede this call with an output of a newline and to avoid doing so</span></div>
<div class="line"><a id="l00405" name="l00405"></a><span class="lineno">  405</span><span class="comment"> *     after that call (unless blank line is desired).</span></div>
<div class="line"><a id="l00406" name="l00406"></a><span class="lineno">  406</span><span class="comment"> *</span></div>
<div class="line"><a id="l00407" name="l00407"></a><span class="lineno">  407</span><span class="comment"> * Example with a single contiguous memory area, multi-line mode:</span></div>
<div class="line"><a id="l00408" name="l00408"></a><span class="lineno">  408</span><span class="comment"> *</span></div>
<div class="line"><a id="l00409" name="l00409"></a><span class="lineno">  409</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00410" name="l00410"></a><span class="lineno">  410</span><span class="comment"> *   array&lt;uint8_t, 256 * 256&gt; bytes(...);</span></div>
<div class="line"><a id="l00411" name="l00411"></a><span class="lineno">  411</span><span class="comment"> *</span></div>
<div class="line"><a id="l00412" name="l00412"></a><span class="lineno">  412</span><span class="comment"> *   // Output to cout.</span></div>
<div class="line"><a id="l00413" name="l00413"></a><span class="lineno">  413</span><span class="comment"> *   cout</span></div>
<div class="line"><a id="l00414" name="l00414"></a><span class="lineno">  414</span><span class="comment"> *     &lt;&lt; &quot;Buffer contents: [\n&quot;;</span></div>
<div class="line"><a id="l00415" name="l00415"></a><span class="lineno">  415</span><span class="comment"> *   buffers_to_ostream(cout,</span></div>
<div class="line"><a id="l00416" name="l00416"></a><span class="lineno">  416</span><span class="comment"> *                      boost::asio::buffer(bytes), // Turn a single memory array into a buffer sequence.</span></div>
<div class="line"><a id="l00417" name="l00417"></a><span class="lineno">  417</span><span class="comment"> *                      &quot;  &quot;);</span></div>
<div class="line"><a id="l00418" name="l00418"></a><span class="lineno">  418</span><span class="comment"> *     &lt;&lt; &quot;].&quot;; // This will be on its own line at the end.</span></div>
<div class="line"><a id="l00419" name="l00419"></a><span class="lineno">  419</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00420" name="l00420"></a><span class="lineno">  420</span><span class="comment"> *</span></div>
<div class="line"><a id="l00421" name="l00421"></a><span class="lineno">  421</span><span class="comment"> * See also buffers_dump_string() which returns a string and can thus be more easily used directly inside</span></div>
<div class="line"><a id="l00422" name="l00422"></a><span class="lineno">  422</span><span class="comment"> * FLOW_LOG_DATA() and similar log macros.</span></div>
<div class="line"><a id="l00423" name="l00423"></a><span class="lineno">  423</span><span class="comment"> *</span></div>
<div class="line"><a id="l00424" name="l00424"></a><span class="lineno">  424</span><span class="comment"> * ### Performance ###</span></div>
<div class="line"><a id="l00425" name="l00425"></a><span class="lineno">  425</span><span class="comment"> * This thing is slow... it&#39;s not trying to be fast and can&#39;t be all that fast anyway.  As usual, though, if used</span></div>
<div class="line"><a id="l00426" name="l00426"></a><span class="lineno">  426</span><span class="comment"> * in FLOW_LOG_DATA() (etc.) its slowness will only come into play if the log filter passes which (esp. for</span></div>
<div class="line"><a id="l00427" name="l00427"></a><span class="lineno">  427</span><span class="comment"> * log::Severity::S_DATA) it usually won&#39;t.</span></div>
<div class="line"><a id="l00428" name="l00428"></a><span class="lineno">  428</span><span class="comment"> *</span></div>
<div class="line"><a id="l00429" name="l00429"></a><span class="lineno">  429</span><span class="comment"> * That said buffers_dump_string() is even slower, because it&#39;ll use an intermediate `ostream` independent of whatever</span></div>
<div class="line"><a id="l00430" name="l00430"></a><span class="lineno">  430</span><span class="comment"> * `ostream` you may or may not be placing the resulting string.  However it&#39;s easier to use with `FLOW_LOG_...()`,</span></div>
<div class="line"><a id="l00431" name="l00431"></a><span class="lineno">  431</span><span class="comment"> * and since in that case perf is typically not an issue, it makes sense to use the easier thing typically.</span></div>
<div class="line"><a id="l00432" name="l00432"></a><span class="lineno">  432</span><span class="comment"> *</span></div>
<div class="line"><a id="l00433" name="l00433"></a><span class="lineno">  433</span><span class="comment"> * However, if you do want to avoid that extra copy and need to *also* use buffers_to_ostream() directly inside</span></div>
<div class="line"><a id="l00434" name="l00434"></a><span class="lineno">  434</span><span class="comment"> * `FLOW_LOG_...()` then the following technique isn&#39;t too wordy and works:</span></div>
<div class="line"><a id="l00435" name="l00435"></a><span class="lineno">  435</span><span class="comment"> *</span></div>
<div class="line"><a id="l00436" name="l00436"></a><span class="lineno">  436</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00437" name="l00437"></a><span class="lineno">  437</span><span class="comment"> *   const array&lt;uint8_t, 256 * 256&gt; bytes(...);</span></div>
<div class="line"><a id="l00438" name="l00438"></a><span class="lineno">  438</span><span class="comment"> *</span></div>
<div class="line"><a id="l00439" name="l00439"></a><span class="lineno">  439</span><span class="comment"> *   // Log with a flow::log macro.</span></div>
<div class="line"><a id="l00440" name="l00440"></a><span class="lineno">  440</span><span class="comment"> *   const flow::Function&lt;ostream&amp; (ostream&amp;)&gt; os_manip = [&amp;](ostream&amp; os) -&gt; ostream&amp;</span></div>
<div class="line"><a id="l00441" name="l00441"></a><span class="lineno">  441</span><span class="comment"> *   {</span></div>
<div class="line"><a id="l00442" name="l00442"></a><span class="lineno">  442</span><span class="comment"> *     return buffers_to_ostream(os, boost::asio::buffer(bytes), &quot;  &quot;);</span></div>
<div class="line"><a id="l00443" name="l00443"></a><span class="lineno">  443</span><span class="comment"> *   };</span></div>
<div class="line"><a id="l00444" name="l00444"></a><span class="lineno">  444</span><span class="comment"> *   FLOW_LOG_INFO(&quot;Buffer contents: [\n&quot; &lt;&lt; os_manip &lt;&lt; &quot;].&quot;);</span></div>
<div class="line"><a id="l00445" name="l00445"></a><span class="lineno">  445</span><span class="comment"> *</span></div>
<div class="line"><a id="l00446" name="l00446"></a><span class="lineno">  446</span><span class="comment"> *   // Above is probably more performant than:</span></div>
<div class="line"><a id="l00447" name="l00447"></a><span class="lineno">  447</span><span class="comment"> *   FLOW_LOG_INFO(&quot;Buffer contents: [\n&quot;</span></div>
<div class="line"><a id="l00448" name="l00448"></a><span class="lineno">  448</span><span class="comment"> *                 &lt;&lt; buffers_dump_string(boost::asio::buffer(bytes), &quot;  &quot;) // Intermediate+copy, slow....</span></div>
<div class="line"><a id="l00449" name="l00449"></a><span class="lineno">  449</span><span class="comment"> *                 &lt;&lt; &quot;].&quot;);</span></div>
<div class="line"><a id="l00450" name="l00450"></a><span class="lineno">  450</span><span class="comment"> *   // flow::util::ostream_op_string() is a bit of an improvement but still. :-)</span></div>
<div class="line"><a id="l00451" name="l00451"></a><span class="lineno">  451</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00452" name="l00452"></a><span class="lineno">  452</span><span class="comment"> *</span></div>
<div class="line"><a id="l00453" name="l00453"></a><span class="lineno">  453</span><span class="comment"> * ### Rationale ###</span></div>
<div class="line"><a id="l00454" name="l00454"></a><span class="lineno">  454</span><span class="comment"> * The reason it returns `os` and takes a reference-to-mutable instead of the customary (for this project&#39;s</span></div>
<div class="line"><a id="l00455" name="l00455"></a><span class="lineno">  455</span><span class="comment"> * style, to indicate modification potential at call sites) pointer-to-mutable is in order to be `bind()`able</span></div>
<div class="line"><a id="l00456" name="l00456"></a><span class="lineno">  456</span><span class="comment"> * in such a way as to make an `ostream` manipulator.  In the example above we use a lambda instead of `bind()`</span></div>
<div class="line"><a id="l00457" name="l00457"></a><span class="lineno">  457</span><span class="comment"> * however.</span></div>
<div class="line"><a id="l00458" name="l00458"></a><span class="lineno">  458</span><span class="comment"> *</span></div>
<div class="line"><a id="l00459" name="l00459"></a><span class="lineno">  459</span><span class="comment"> * @tparam Const_buffer_sequence</span></div>
<div class="line"><a id="l00460" name="l00460"></a><span class="lineno">  460</span><span class="comment"> *         Type that models the boost.asio `ConstBufferSequence` concept (see Boost docs) which represents</span></div>
<div class="line"><a id="l00461" name="l00461"></a><span class="lineno">  461</span><span class="comment"> *         1 or more scattered buffers in memory (only 1 buffer in a sequence is common).</span></div>
<div class="line"><a id="l00462" name="l00462"></a><span class="lineno">  462</span><span class="comment"> *         In particular `boost::asio::const_buffer` works when dumping a single buffer.</span></div>
<div class="line"><a id="l00463" name="l00463"></a><span class="lineno">  463</span><span class="comment"> * @param os</span></div>
<div class="line"><a id="l00464" name="l00464"></a><span class="lineno">  464</span><span class="comment"> *        The output stream to which to write.</span></div>
<div class="line"><a id="l00465" name="l00465"></a><span class="lineno">  465</span><span class="comment"> * @param data</span></div>
<div class="line"><a id="l00466" name="l00466"></a><span class="lineno">  466</span><span class="comment"> *        The data to write, given as an immutable sequence of buffers each of which is essentially a pointer</span></div>
<div class="line"><a id="l00467" name="l00467"></a><span class="lineno">  467</span><span class="comment"> *        and length.  (Reminder: it is trivial to make such an object from a single buffer as well;</span></div>
<div class="line"><a id="l00468" name="l00468"></a><span class="lineno">  468</span><span class="comment"> *        for example given `array&lt;uint8_t, 256&gt; data` (an array of 256 bytes), you can just pass</span></div>
<div class="line"><a id="l00469" name="l00469"></a><span class="lineno">  469</span><span class="comment"> *        `boost::asio::buffer(data)`, as the latter returns an object whose type satisfies requirements of</span></div>
<div class="line"><a id="l00470" name="l00470"></a><span class="lineno">  470</span><span class="comment"> *        `Const_buffer_sequence` despite the original memory area being nothing more than a single</span></div>
<div class="line"><a id="l00471" name="l00471"></a><span class="lineno">  471</span><span class="comment"> *        byte array.)</span></div>
<div class="line"><a id="l00472" name="l00472"></a><span class="lineno">  472</span><span class="comment"> * @param indentation</span></div>
<div class="line"><a id="l00473" name="l00473"></a><span class="lineno">  473</span><span class="comment"> *        The indentation to use at the start of every line of output.</span></div>
<div class="line"><a id="l00474" name="l00474"></a><span class="lineno">  474</span><span class="comment"> * @param bytes_per_line</span></div>
<div class="line"><a id="l00475" name="l00475"></a><span class="lineno">  475</span><span class="comment"> *        If 0, act as-if a certain default positive value were passed; and then: If `-1`, single-line mode is invoked.</span></div>
<div class="line"><a id="l00476" name="l00476"></a><span class="lineno">  476</span><span class="comment"> *        If a positive value, multi-line mode is invoked, with all lines but the last one consisting of</span></div>
<div class="line"><a id="l00477" name="l00477"></a><span class="lineno">  477</span><span class="comment"> *        a dump of that many contiguous bytes of `data`.  (Yes, multi-line mode is still in force, even if there</span></div>
<div class="line"><a id="l00478" name="l00478"></a><span class="lineno">  478</span><span class="comment"> *        are only enough bytes in `data` for one line of output anyway.)</span></div>
<div class="line"><a id="l00479" name="l00479"></a><span class="lineno">  479</span><span class="comment"> * @return `os`.</span></div>
<div class="line"><a id="l00480" name="l00480"></a><span class="lineno">  480</span><span class="comment"> */</span></div>
<div class="line"><a id="l00481" name="l00481"></a><span class="lineno">  481</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Const_buffer_sequence&gt;</div>
<div class="line"><a id="l00482" name="l00482"></a><span class="lineno">  482</span>std::ostream&amp; <a class="code hl_function" href="namespaceflow_1_1util.html#aa132928b364caefca5c3821e019924bf">buffers_to_ostream</a>(std::ostream&amp; os, <span class="keyword">const</span> Const_buffer_sequence&amp; data, <span class="keyword">const</span> std::string&amp; indentation,</div>
<div class="line"><a id="l00483" name="l00483"></a><span class="lineno">  483</span>                                 <span class="keywordtype">size_t</span> bytes_per_line = 0);</div>
<div class="line"><a id="l00484" name="l00484"></a><span class="lineno">  484</span><span class="comment"></span> </div>
<div class="line"><a id="l00485" name="l00485"></a><span class="lineno">  485</span><span class="comment">/**</span></div>
<div class="line"><a id="l00486" name="l00486"></a><span class="lineno">  486</span><span class="comment"> * Identical to buffers_to_ostream() but returns an `std::string` instead of writing to a given `ostream`.</span></div>
<div class="line"><a id="l00487" name="l00487"></a><span class="lineno">  487</span><span class="comment"> *</span></div>
<div class="line"><a id="l00488" name="l00488"></a><span class="lineno">  488</span><span class="comment"> * @see buffers_to_ostream() doc header for notes on performance and usability.</span></div>
<div class="line"><a id="l00489" name="l00489"></a><span class="lineno">  489</span><span class="comment"> *</span></div>
<div class="line"><a id="l00490" name="l00490"></a><span class="lineno">  490</span><span class="comment"> * @tparam Const_buffer_sequence</span></div>
<div class="line"><a id="l00491" name="l00491"></a><span class="lineno">  491</span><span class="comment"> *         See buffers_to_ostream().</span></div>
<div class="line"><a id="l00492" name="l00492"></a><span class="lineno">  492</span><span class="comment"> * @param data</span></div>
<div class="line"><a id="l00493" name="l00493"></a><span class="lineno">  493</span><span class="comment"> *        See buffers_to_ostream().</span></div>
<div class="line"><a id="l00494" name="l00494"></a><span class="lineno">  494</span><span class="comment"> * @param indentation</span></div>
<div class="line"><a id="l00495" name="l00495"></a><span class="lineno">  495</span><span class="comment"> *        See buffers_to_ostream().</span></div>
<div class="line"><a id="l00496" name="l00496"></a><span class="lineno">  496</span><span class="comment"> * @param bytes_per_line</span></div>
<div class="line"><a id="l00497" name="l00497"></a><span class="lineno">  497</span><span class="comment"> *        See buffers_to_ostream().</span></div>
<div class="line"><a id="l00498" name="l00498"></a><span class="lineno">  498</span><span class="comment"> * @return Result string.</span></div>
<div class="line"><a id="l00499" name="l00499"></a><span class="lineno">  499</span><span class="comment"> */</span></div>
<div class="line"><a id="l00500" name="l00500"></a><span class="lineno">  500</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Const_buffer_sequence&gt;</div>
<div class="line"><a id="l00501" name="l00501"></a><span class="lineno">  501</span>std::string <a class="code hl_function" href="namespaceflow_1_1util.html#a16357344c21456b86b7de3085e2661a2">buffers_dump_string</a>(<span class="keyword">const</span> Const_buffer_sequence&amp; data, <span class="keyword">const</span> std::string&amp; indentation,</div>
<div class="line"><a id="l00502" name="l00502"></a><span class="lineno">  502</span>                                <span class="keywordtype">size_t</span> bytes_per_line = 0);</div>
<div class="line"><a id="l00503" name="l00503"></a><span class="lineno">  503</span><span class="comment"></span> </div>
<div class="line"><a id="l00504" name="l00504"></a><span class="lineno">  504</span><span class="comment">/**</span></div>
<div class="line"><a id="l00505" name="l00505"></a><span class="lineno">  505</span><span class="comment"> * Utility that converts a bandwidth in arbitrary units in both numerator and denominator to the same bandwidth</span></div>
<div class="line"><a id="l00506" name="l00506"></a><span class="lineno">  506</span><span class="comment"> * in megabits per second.  The input bandwidth is given in &quot;items&quot; per `Time_unit(1)`; where `Time_unit` is an</span></div>
<div class="line"><a id="l00507" name="l00507"></a><span class="lineno">  507</span><span class="comment"> * arbitrary boost.chrono `duration` type that must be explicitly provided as input; and an &quot;item&quot; is defined</span></div>
<div class="line"><a id="l00508" name="l00508"></a><span class="lineno">  508</span><span class="comment"> * as `bits_per_item` bits.  Useful at least for logging.  It&#39;s probably easiest to understand by example; see below;</span></div>
<div class="line"><a id="l00509" name="l00509"></a><span class="lineno">  509</span><span class="comment"> * rather than by parsing that description I just wrote.</span></div>
<div class="line"><a id="l00510" name="l00510"></a><span class="lineno">  510</span><span class="comment"> *</span></div>
<div class="line"><a id="l00511" name="l00511"></a><span class="lineno">  511</span><span class="comment"> * To be clear (as C++ syntax is not super-expressive in this case) -- the template parameter `Time_unit` is</span></div>
<div class="line"><a id="l00512" name="l00512"></a><span class="lineno">  512</span><span class="comment"> * an explicit input to the function template, essentially instructing it as to in what units `items_per_time` is.</span></div>
<div class="line"><a id="l00513" name="l00513"></a><span class="lineno">  513</span><span class="comment"> * Thus all uses of this function should look similar to:</span></div>
<div class="line"><a id="l00514" name="l00514"></a><span class="lineno">  514</span><span class="comment"> *</span></div>
<div class="line"><a id="l00515" name="l00515"></a><span class="lineno">  515</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00516" name="l00516"></a><span class="lineno">  516</span><span class="comment"> *   // These are all equal doubles, because the (value, unit represented by value) pair is logically same in each case.</span></div>
<div class="line"><a id="l00517" name="l00517"></a><span class="lineno">  517</span><span class="comment"> *</span></div>
<div class="line"><a id="l00518" name="l00518"></a><span class="lineno">  518</span><span class="comment"> *   // We&#39;ll repeatedly convert from 2400 mebibytes (1024 * 1024 bytes) per second, represented one way or another.</span></div>
<div class="line"><a id="l00519" name="l00519"></a><span class="lineno">  519</span><span class="comment"> *   const size_t MB_PER_SEC = 2400;</span></div>
<div class="line"><a id="l00520" name="l00520"></a><span class="lineno">  520</span><span class="comment"> *</span></div>
<div class="line"><a id="l00521" name="l00521"></a><span class="lineno">  521</span><span class="comment"> *   // First give it as _mebibytes_ (2nd arg) per _second_ (template arg).</span></div>
<div class="line"><a id="l00522" name="l00522"></a><span class="lineno">  522</span><span class="comment"> *   const double mbps_from_mb_per_sec</span></div>
<div class="line"><a id="l00523" name="l00523"></a><span class="lineno">  523</span><span class="comment"> *     = flow::util::to_mbit_per_sec&lt;chrono::seconds&gt;(MB_PER_SEC, 1024 * 8);</span></div>
<div class="line"><a id="l00524" name="l00524"></a><span class="lineno">  524</span><span class="comment"> *</span></div>
<div class="line"><a id="l00525" name="l00525"></a><span class="lineno">  525</span><span class="comment"> *   // Now give it as _bytes_ (2nd arg omitted in favor of very common default = 8) per _second_ (template arg).</span></div>
<div class="line"><a id="l00526" name="l00526"></a><span class="lineno">  526</span><span class="comment"> *   const double mbps_from_b_per_sec</span></div>
<div class="line"><a id="l00527" name="l00527"></a><span class="lineno">  527</span><span class="comment"> *     = flow::util::to_mbit_per_sec&lt;chrono::seconds&gt;(MB_PER_SEC * 1024 * 1024);</span></div>
<div class="line"><a id="l00528" name="l00528"></a><span class="lineno">  528</span><span class="comment"> *</span></div>
<div class="line"><a id="l00529" name="l00529"></a><span class="lineno">  529</span><span class="comment"> *   // Now in _bytes_ per _hour_.</span></div>
<div class="line"><a id="l00530" name="l00530"></a><span class="lineno">  530</span><span class="comment"> *   const double mbps_from_b_per_hour</span></div>
<div class="line"><a id="l00531" name="l00531"></a><span class="lineno">  531</span><span class="comment"> *     = flow::util::to_mbit_per_sec&lt;chrono::hours&gt;(MB_PER_SEC * 1024 * 1024 * 60 * 60);</span></div>
<div class="line"><a id="l00532" name="l00532"></a><span class="lineno">  532</span><span class="comment"> *</span></div>
<div class="line"><a id="l00533" name="l00533"></a><span class="lineno">  533</span><span class="comment"> *   // Finally give it in _bytes_ per _1/30th-of-a-second_ (i.e., per frame, when the frame rate is 30fps).</span></div>
<div class="line"><a id="l00534" name="l00534"></a><span class="lineno">  534</span><span class="comment"> *   const double mbps_from_b_per_30fps_frame</span></div>
<div class="line"><a id="l00535" name="l00535"></a><span class="lineno">  535</span><span class="comment"> *     = flow::util::to_mbit_per_sec&lt;chrono::duration&lt;int, ratio&lt;1, 30&gt;&gt;(MB_PER_SEC * 1024 * 1024 / 30);</span></div>
<div class="line"><a id="l00536" name="l00536"></a><span class="lineno">  536</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00537" name="l00537"></a><span class="lineno">  537</span><span class="comment"> *</span></div>
<div class="line"><a id="l00538" name="l00538"></a><span class="lineno">  538</span><span class="comment"> * @note Megabit (1000 x 1000 = 10^6 bits) =/= mebibit (1024 x 1024 = 2^20 bits); but the latter is only about 5% more.</span></div>
<div class="line"><a id="l00539" name="l00539"></a><span class="lineno">  539</span><span class="comment"> * @todo boost.unit &quot;feels&quot; like it would do this for us in some amazingly pithy and just-as-fast way.  Because Boost.</span></div>
<div class="line"><a id="l00540" name="l00540"></a><span class="lineno">  540</span><span class="comment"> * @tparam Time_unit</span></div>
<div class="line"><a id="l00541" name="l00541"></a><span class="lineno">  541</span><span class="comment"> *         `boost::chrono::duration&lt;Rep, Period&gt;` for some specific `Rep` and `Period`.</span></div>
<div class="line"><a id="l00542" name="l00542"></a><span class="lineno">  542</span><span class="comment"> *         See `boost::chrono::duration` documentation.</span></div>
<div class="line"><a id="l00543" name="l00543"></a><span class="lineno">  543</span><span class="comment"> *         Example types: `boost::chrono::milliseconds`; `boost::chrono::seconds`; see example use code above.</span></div>
<div class="line"><a id="l00544" name="l00544"></a><span class="lineno">  544</span><span class="comment"> * @tparam N_items</span></div>
<div class="line"><a id="l00545" name="l00545"></a><span class="lineno">  545</span><span class="comment"> *         Some (not necessarily integral) numeric type.  Strictly speaking, any type convertible to `double` works.</span></div>
<div class="line"><a id="l00546" name="l00546"></a><span class="lineno">  546</span><span class="comment"> * @param items_per_time</span></div>
<div class="line"><a id="l00547" name="l00547"></a><span class="lineno">  547</span><span class="comment"> *        The value, in items per `Time_unit(1)` (where there are `bits_per_item` bits in 1 item) to convert to</span></div>
<div class="line"><a id="l00548" name="l00548"></a><span class="lineno">  548</span><span class="comment"> *        megabits per second.  Note this need not be an integer.</span></div>
<div class="line"><a id="l00549" name="l00549"></a><span class="lineno">  549</span><span class="comment"> * @param bits_per_item</span></div>
<div class="line"><a id="l00550" name="l00550"></a><span class="lineno">  550</span><span class="comment"> *        Number of bits in an item, where `items_per_time` is given as a number of items.</span></div>
<div class="line"><a id="l00551" name="l00551"></a><span class="lineno">  551</span><span class="comment"> * @return See above.</span></div>
<div class="line"><a id="l00552" name="l00552"></a><span class="lineno">  552</span><span class="comment"> */</span></div>
<div class="line"><a id="l00553" name="l00553"></a><span class="lineno">  553</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Time_unit, <span class="keyword">typename</span> N_items&gt;</div>
<div class="line"><a id="l00554" name="l00554"></a><span class="lineno">  554</span><span class="keywordtype">double</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a0f681afaf67a0f917cf43a7ae893a015">to_mbit_per_sec</a>(N_items items_per_time, <span class="keywordtype">size_t</span> bits_per_item = 8);</div>
<div class="line"><a id="l00555" name="l00555"></a><span class="lineno">  555</span><span class="comment"></span> </div>
<div class="line"><a id="l00556" name="l00556"></a><span class="lineno">  556</span><span class="comment">/**</span></div>
<div class="line"><a id="l00557" name="l00557"></a><span class="lineno">  557</span><span class="comment"> * Returns the result of the given non-negative integer divided by a positive integer, rounded up to the nearest</span></div>
<div class="line"><a id="l00558" name="l00558"></a><span class="lineno">  558</span><span class="comment"> * integer.  Internally, it avoids floating-point math for performance.</span></div>
<div class="line"><a id="l00559" name="l00559"></a><span class="lineno">  559</span><span class="comment"> *</span></div>
<div class="line"><a id="l00560" name="l00560"></a><span class="lineno">  560</span><span class="comment"> * @tparam Integer</span></div>
<div class="line"><a id="l00561" name="l00561"></a><span class="lineno">  561</span><span class="comment"> *         A signed or unsigned integral type.</span></div>
<div class="line"><a id="l00562" name="l00562"></a><span class="lineno">  562</span><span class="comment"> * @param dividend</span></div>
<div class="line"><a id="l00563" name="l00563"></a><span class="lineno">  563</span><span class="comment"> *        Dividend; non-negative or assertion trips.</span></div>
<div class="line"><a id="l00564" name="l00564"></a><span class="lineno">  564</span><span class="comment"> * @param divisor</span></div>
<div class="line"><a id="l00565" name="l00565"></a><span class="lineno">  565</span><span class="comment"> *        Divisor; positive or assertion trips.</span></div>
<div class="line"><a id="l00566" name="l00566"></a><span class="lineno">  566</span><span class="comment"> * @return Ceiling of `(dividend / divisor)`.</span></div>
<div class="line"><a id="l00567" name="l00567"></a><span class="lineno">  567</span><span class="comment"> */</span></div>
<div class="line"><a id="l00568" name="l00568"></a><span class="lineno">  568</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Integer&gt;</div>
<div class="line"><a id="l00569" name="l00569"></a><span class="lineno">  569</span>Integer <a class="code hl_function" href="namespaceflow_1_1util.html#a6b7316b3ed6d89f54c91e17c2aab101e">ceil_div</a>(Integer dividend, Integer divisor);</div>
<div class="line"><a id="l00570" name="l00570"></a><span class="lineno">  570</span><span class="comment"></span> </div>
<div class="line"><a id="l00571" name="l00571"></a><span class="lineno">  571</span><span class="comment">/**</span></div>
<div class="line"><a id="l00572" name="l00572"></a><span class="lineno">  572</span><span class="comment"> * Provides a way to execute arbitrary (cleanup) code at the exit of the current block.  Simply</span></div>
<div class="line"><a id="l00573" name="l00573"></a><span class="lineno">  573</span><span class="comment"> * save the returned object into a local variable that will go out of scope when your code block</span></div>
<div class="line"><a id="l00574" name="l00574"></a><span class="lineno">  574</span><span class="comment"> * exits.  Example:</span></div>
<div class="line"><a id="l00575" name="l00575"></a><span class="lineno">  575</span><span class="comment"> *</span></div>
<div class="line"><a id="l00576" name="l00576"></a><span class="lineno">  576</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00577" name="l00577"></a><span class="lineno">  577</span><span class="comment"> *   {</span></div>
<div class="line"><a id="l00578" name="l00578"></a><span class="lineno">  578</span><span class="comment"> *     X* x = create_x();</span></div>
<div class="line"><a id="l00579" name="l00579"></a><span class="lineno">  579</span><span class="comment"> *     auto cleanup = util::setup_auto_cleanup([&amp;]() { delete_x(x); });</span></div>
<div class="line"><a id="l00580" name="l00580"></a><span class="lineno">  580</span><span class="comment"> *     // Now delete_x(x) will be called no matter how the current { block } exits.</span></div>
<div class="line"><a id="l00581" name="l00581"></a><span class="lineno">  581</span><span class="comment"> *     // ...</span></div>
<div class="line"><a id="l00582" name="l00582"></a><span class="lineno">  582</span><span class="comment"> *   }</span></div>
<div class="line"><a id="l00583" name="l00583"></a><span class="lineno">  583</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00584" name="l00584"></a><span class="lineno">  584</span><span class="comment"> *</span></div>
<div class="line"><a id="l00585" name="l00585"></a><span class="lineno">  585</span><span class="comment"> * @todo setup_auto_cleanup() should take a function via move semantics.</span></div>
<div class="line"><a id="l00586" name="l00586"></a><span class="lineno">  586</span><span class="comment"> *</span></div>
<div class="line"><a id="l00587" name="l00587"></a><span class="lineno">  587</span><span class="comment"> * @tparam Cleanup_func</span></div>
<div class="line"><a id="l00588" name="l00588"></a><span class="lineno">  588</span><span class="comment"> *         Any type such that given an instance `Cleanup_func f`, the expression `f()` is valid.</span></div>
<div class="line"><a id="l00589" name="l00589"></a><span class="lineno">  589</span><span class="comment"> * @param func</span></div>
<div class="line"><a id="l00590" name="l00590"></a><span class="lineno">  590</span><span class="comment"> *        `func()` will be called when cleanup is needed.</span></div>
<div class="line"><a id="l00591" name="l00591"></a><span class="lineno">  591</span><span class="comment"> * @return A light-weight object that, when it goes out of scope, will cause `func()` to be called.</span></div>
<div class="line"><a id="l00592" name="l00592"></a><span class="lineno">  592</span><span class="comment"> */</span></div>
<div class="line"><a id="l00593" name="l00593"></a><span class="lineno">  593</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Cleanup_func&gt;</div>
<div class="line"><a id="l00594" name="l00594"></a><span class="lineno">  594</span><a class="code hl_typedef" href="namespaceflow_1_1util.html#ab22fd89e165a9e6deaa174bc0dfdc8de">Auto_cleanup</a> <a class="code hl_function" href="namespaceflow_1_1util.html#a09a032f8e1e77a3afc0b7df115a773e1">setup_auto_cleanup</a>(<span class="keyword">const</span> Cleanup_func&amp; func);</div>
<div class="line"><a id="l00595" name="l00595"></a><span class="lineno">  595</span><span class="comment"></span> </div>
<div class="line"><a id="l00596" name="l00596"></a><span class="lineno">  596</span><span class="comment">/**</span></div>
<div class="line"><a id="l00597" name="l00597"></a><span class="lineno">  597</span><span class="comment"> * Returns `true` if and only if the given value is within the given range, inclusive.</span></div>
<div class="line"><a id="l00598" name="l00598"></a><span class="lineno">  598</span><span class="comment"> *</span></div>
<div class="line"><a id="l00599" name="l00599"></a><span class="lineno">  599</span><span class="comment"> * @param min_val</span></div>
<div class="line"><a id="l00600" name="l00600"></a><span class="lineno">  600</span><span class="comment"> *        Lower part of the range.</span></div>
<div class="line"><a id="l00601" name="l00601"></a><span class="lineno">  601</span><span class="comment"> * @param val</span></div>
<div class="line"><a id="l00602" name="l00602"></a><span class="lineno">  602</span><span class="comment"> *        Value to check.</span></div>
<div class="line"><a id="l00603" name="l00603"></a><span class="lineno">  603</span><span class="comment"> * @param max_val</span></div>
<div class="line"><a id="l00604" name="l00604"></a><span class="lineno">  604</span><span class="comment"> *        Higher part of the range.  Must be greater than or equal to `min_val`, or behavior is undefined.</span></div>
<div class="line"><a id="l00605" name="l00605"></a><span class="lineno">  605</span><span class="comment"> * @tparam T</span></div>
<div class="line"><a id="l00606" name="l00606"></a><span class="lineno">  606</span><span class="comment"> *         A type for which the operation `x &lt; y` is defined and makes sense.  Examples: `double`, `char`,</span></div>
<div class="line"><a id="l00607" name="l00607"></a><span class="lineno">  607</span><span class="comment"> *         `unsigned int`, #Fine_duration.</span></div>
<div class="line"><a id="l00608" name="l00608"></a><span class="lineno">  608</span><span class="comment"> * @return `true` if and only if `val` is in [`min_val`, `max_val`].</span></div>
<div class="line"><a id="l00609" name="l00609"></a><span class="lineno">  609</span><span class="comment"> */</span></div>
<div class="line"><a id="l00610" name="l00610"></a><span class="lineno">  610</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T&gt;</div>
<div class="line"><a id="l00611" name="l00611"></a><span class="lineno">  611</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#ab10bc9e8bef148f875aa743fe0852743">in_closed_range</a>(T <span class="keyword">const</span> &amp; min_val, T <span class="keyword">const</span> &amp; val, T <span class="keyword">const</span> &amp; max_val);</div>
<div class="line"><a id="l00612" name="l00612"></a><span class="lineno">  612</span><span class="comment"></span> </div>
<div class="line"><a id="l00613" name="l00613"></a><span class="lineno">  613</span><span class="comment">/**</span></div>
<div class="line"><a id="l00614" name="l00614"></a><span class="lineno">  614</span><span class="comment"> * Returns `true` if and only if the given value is within the given range, given as a [low, high)</span></div>
<div class="line"><a id="l00615" name="l00615"></a><span class="lineno">  615</span><span class="comment"> * pair.</span></div>
<div class="line"><a id="l00616" name="l00616"></a><span class="lineno">  616</span><span class="comment"> *</span></div>
<div class="line"><a id="l00617" name="l00617"></a><span class="lineno">  617</span><span class="comment"> * @param min_val</span></div>
<div class="line"><a id="l00618" name="l00618"></a><span class="lineno">  618</span><span class="comment"> *        Lower part of the range.</span></div>
<div class="line"><a id="l00619" name="l00619"></a><span class="lineno">  619</span><span class="comment"> * @param val</span></div>
<div class="line"><a id="l00620" name="l00620"></a><span class="lineno">  620</span><span class="comment"> *        Value to check.</span></div>
<div class="line"><a id="l00621" name="l00621"></a><span class="lineno">  621</span><span class="comment"> * @param max_val</span></div>
<div class="line"><a id="l00622" name="l00622"></a><span class="lineno">  622</span><span class="comment"> *        Higher part of the range.  Must be greater than `min_val`, or behavior is undefined.</span></div>
<div class="line"><a id="l00623" name="l00623"></a><span class="lineno">  623</span><span class="comment"> * @tparam T</span></div>
<div class="line"><a id="l00624" name="l00624"></a><span class="lineno">  624</span><span class="comment"> *         A type for which the operation `x &lt; y` is defined and makes sense.  Examples: `double`, `char`,</span></div>
<div class="line"><a id="l00625" name="l00625"></a><span class="lineno">  625</span><span class="comment"> *         `unsigned int`, #Fine_duration.</span></div>
<div class="line"><a id="l00626" name="l00626"></a><span class="lineno">  626</span><span class="comment"> * @return `true` if and only if `val` is in [`min_val`, `max_val`), i.e., `min_val` &lt;= `val` &lt; `max_val`.</span></div>
<div class="line"><a id="l00627" name="l00627"></a><span class="lineno">  627</span><span class="comment"> */</span></div>
<div class="line"><a id="l00628" name="l00628"></a><span class="lineno">  628</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T&gt;</div>
<div class="line"><a id="l00629" name="l00629"></a><span class="lineno">  629</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a024ddda9acb2b66f2a1b35cdb0c016aa">in_closed_open_range</a>(T <span class="keyword">const</span> &amp; min_val, T <span class="keyword">const</span> &amp; val, T <span class="keyword">const</span> &amp; max_val);</div>
<div class="line"><a id="l00630" name="l00630"></a><span class="lineno">  630</span><span class="comment"></span> </div>
<div class="line"><a id="l00631" name="l00631"></a><span class="lineno">  631</span><span class="comment">/**</span></div>
<div class="line"><a id="l00632" name="l00632"></a><span class="lineno">  632</span><span class="comment"> * Returns `true` if and only if the given value is within the given range, given as a (low, high]</span></div>
<div class="line"><a id="l00633" name="l00633"></a><span class="lineno">  633</span><span class="comment"> * pair.</span></div>
<div class="line"><a id="l00634" name="l00634"></a><span class="lineno">  634</span><span class="comment"> *</span></div>
<div class="line"><a id="l00635" name="l00635"></a><span class="lineno">  635</span><span class="comment"> * @param min_val</span></div>
<div class="line"><a id="l00636" name="l00636"></a><span class="lineno">  636</span><span class="comment"> *        Lower part of the range.</span></div>
<div class="line"><a id="l00637" name="l00637"></a><span class="lineno">  637</span><span class="comment"> * @param val</span></div>
<div class="line"><a id="l00638" name="l00638"></a><span class="lineno">  638</span><span class="comment"> *        Value to check.</span></div>
<div class="line"><a id="l00639" name="l00639"></a><span class="lineno">  639</span><span class="comment"> * @param max_val</span></div>
<div class="line"><a id="l00640" name="l00640"></a><span class="lineno">  640</span><span class="comment"> *        Higher part of the range.  Must be greater than `min_val`, or behavior is undefined.</span></div>
<div class="line"><a id="l00641" name="l00641"></a><span class="lineno">  641</span><span class="comment"> * @tparam T</span></div>
<div class="line"><a id="l00642" name="l00642"></a><span class="lineno">  642</span><span class="comment"> *         A type for which the operation `x &lt; y` is defined and makes sense.  Examples: `double`, `char`,</span></div>
<div class="line"><a id="l00643" name="l00643"></a><span class="lineno">  643</span><span class="comment"> *         `unsigned int`, #Fine_duration.</span></div>
<div class="line"><a id="l00644" name="l00644"></a><span class="lineno">  644</span><span class="comment"> * @return `true` if and only if `val` is in (`min_val`, `max_val`], i.e., `min_val` &lt; `val` &lt;= `max_val`.</span></div>
<div class="line"><a id="l00645" name="l00645"></a><span class="lineno">  645</span><span class="comment"> */</span></div>
<div class="line"><a id="l00646" name="l00646"></a><span class="lineno">  646</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T&gt;</div>
<div class="line"><a id="l00647" name="l00647"></a><span class="lineno">  647</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a8ae762ea4f743a98a73953d7f9ec2164">in_open_closed_range</a>(T <span class="keyword">const</span> &amp; min_val, T <span class="keyword">const</span> &amp; val, T <span class="keyword">const</span> &amp; max_val);</div>
<div class="line"><a id="l00648" name="l00648"></a><span class="lineno">  648</span><span class="comment"></span> </div>
<div class="line"><a id="l00649" name="l00649"></a><span class="lineno">  649</span><span class="comment">/**</span></div>
<div class="line"><a id="l00650" name="l00650"></a><span class="lineno">  650</span><span class="comment"> * Returns `true` if and only if the given value is within the given range, given as a (low, high)</span></div>
<div class="line"><a id="l00651" name="l00651"></a><span class="lineno">  651</span><span class="comment"> * pair.</span></div>
<div class="line"><a id="l00652" name="l00652"></a><span class="lineno">  652</span><span class="comment"> *</span></div>
<div class="line"><a id="l00653" name="l00653"></a><span class="lineno">  653</span><span class="comment"> * @param min_val</span></div>
<div class="line"><a id="l00654" name="l00654"></a><span class="lineno">  654</span><span class="comment"> *        Lower part of the range.</span></div>
<div class="line"><a id="l00655" name="l00655"></a><span class="lineno">  655</span><span class="comment"> * @param val</span></div>
<div class="line"><a id="l00656" name="l00656"></a><span class="lineno">  656</span><span class="comment"> *        Value to check.</span></div>
<div class="line"><a id="l00657" name="l00657"></a><span class="lineno">  657</span><span class="comment"> * @param max_val</span></div>
<div class="line"><a id="l00658" name="l00658"></a><span class="lineno">  658</span><span class="comment"> *        Higher part of the range.  Must be at least 2 greater than `min_val`, or behavior is undefined.</span></div>
<div class="line"><a id="l00659" name="l00659"></a><span class="lineno">  659</span><span class="comment"> * @tparam T</span></div>
<div class="line"><a id="l00660" name="l00660"></a><span class="lineno">  660</span><span class="comment"> *         A type for which the operation `x &lt; y` is defined and makes sense.  Examples: `double`, `char`,</span></div>
<div class="line"><a id="l00661" name="l00661"></a><span class="lineno">  661</span><span class="comment"> *         `unsigned int`, #Fine_duration.</span></div>
<div class="line"><a id="l00662" name="l00662"></a><span class="lineno">  662</span><span class="comment"> * @return `true` if and only if `val` is in (`min_val`, `max_val`), i.e., `min_val` &lt; `val` &lt; `max_val`.</span></div>
<div class="line"><a id="l00663" name="l00663"></a><span class="lineno">  663</span><span class="comment"> */</span></div>
<div class="line"><a id="l00664" name="l00664"></a><span class="lineno">  664</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T&gt;</div>
<div class="line"><a id="l00665" name="l00665"></a><span class="lineno">  665</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a733448fee07c2a77e343a3f1590ff82e">in_open_open_range</a>(T <span class="keyword">const</span> &amp; min_val, T <span class="keyword">const</span> &amp; val, T <span class="keyword">const</span> &amp; max_val);</div>
<div class="line"><a id="l00666" name="l00666"></a><span class="lineno">  666</span><span class="comment"></span> </div>
<div class="line"><a id="l00667" name="l00667"></a><span class="lineno">  667</span><span class="comment">/**</span></div>
<div class="line"><a id="l00668" name="l00668"></a><span class="lineno">  668</span><span class="comment"> * Returns `true` if and only if the given key is present at least once in the given associative</span></div>
<div class="line"><a id="l00669" name="l00669"></a><span class="lineno">  669</span><span class="comment"> * container.</span></div>
<div class="line"><a id="l00670" name="l00670"></a><span class="lineno">  670</span><span class="comment"> *</span></div>
<div class="line"><a id="l00671" name="l00671"></a><span class="lineno">  671</span><span class="comment"> * @tparam Container</span></div>
<div class="line"><a id="l00672" name="l00672"></a><span class="lineno">  672</span><span class="comment"> *         Associative container type (`boost::unordered_map`, `std::set`, etc.).</span></div>
<div class="line"><a id="l00673" name="l00673"></a><span class="lineno">  673</span><span class="comment"> *         In particular must have the members `find()`, `end()`, and `key_type`.</span></div>
<div class="line"><a id="l00674" name="l00674"></a><span class="lineno">  674</span><span class="comment"> * @param container</span></div>
<div class="line"><a id="l00675" name="l00675"></a><span class="lineno">  675</span><span class="comment"> *        Container to search.</span></div>
<div class="line"><a id="l00676" name="l00676"></a><span class="lineno">  676</span><span class="comment"> * @param key</span></div>
<div class="line"><a id="l00677" name="l00677"></a><span class="lineno">  677</span><span class="comment"> *        Key to find.</span></div>
<div class="line"><a id="l00678" name="l00678"></a><span class="lineno">  678</span><span class="comment"> * @return See above.</span></div>
<div class="line"><a id="l00679" name="l00679"></a><span class="lineno">  679</span><span class="comment"> */</span></div>
<div class="line"><a id="l00680" name="l00680"></a><span class="lineno">  680</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Container&gt;</div>
<div class="line"><a id="l00681" name="l00681"></a><span class="lineno">  681</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a03984e29450abf9cf287c501d6c8f866">key_exists</a>(<span class="keyword">const</span> Container&amp; container, <span class="keyword">const</span> <span class="keyword">typename</span> Container::key_type&amp; key);</div>
<div class="line"><a id="l00682" name="l00682"></a><span class="lineno">  682</span><span class="comment"></span> </div>
<div class="line"><a id="l00683" name="l00683"></a><span class="lineno">  683</span><span class="comment">/**</span></div>
<div class="line"><a id="l00684" name="l00684"></a><span class="lineno">  684</span><span class="comment"> * Performs `*minuend -= subtrahend`, subject to a floor of `floor`.  Avoids underflow/overflow to the extent</span></div>
<div class="line"><a id="l00685" name="l00685"></a><span class="lineno">  685</span><span class="comment"> * it&#39;s reasonably possible, but no more.  The return value indicates whether</span></div>
<div class="line"><a id="l00686" name="l00686"></a><span class="lineno">  686</span><span class="comment"> * the floor was hit; this allows one to chain high-performance subtractions like this:</span></div>
<div class="line"><a id="l00687" name="l00687"></a><span class="lineno">  687</span><span class="comment"> *</span></div>
<div class="line"><a id="l00688" name="l00688"></a><span class="lineno">  688</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00689" name="l00689"></a><span class="lineno">  689</span><span class="comment"> *   double t = 44;</span></div>
<div class="line"><a id="l00690" name="l00690"></a><span class="lineno">  690</span><span class="comment"> *   int x = rnd(); // Suppose x == 123, for example.</span></div>
<div class="line"><a id="l00691" name="l00691"></a><span class="lineno">  691</span><span class="comment"> *   // Avoids the 2nd, 3rd computation altogether, as the first detects that x &gt;= 44, and thus t == 0 regardless.</span></div>
<div class="line"><a id="l00692" name="l00692"></a><span class="lineno">  692</span><span class="comment"> *   subtract_with_floor(&amp;t, x) &amp;&amp;</span></div>
<div class="line"><a id="l00693" name="l00693"></a><span class="lineno">  693</span><span class="comment"> *     subtract_with_floor(&amp;t, long_computation()) &amp;&amp;</span></div>
<div class="line"><a id="l00694" name="l00694"></a><span class="lineno">  694</span><span class="comment"> *     subtract_with_floor(&amp;t, another_long_computation());</span></div>
<div class="line"><a id="l00695" name="l00695"></a><span class="lineno">  695</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00696" name="l00696"></a><span class="lineno">  696</span><span class="comment"> *</span></div>
<div class="line"><a id="l00697" name="l00697"></a><span class="lineno">  697</span><span class="comment"> * @tparam Minuend</span></div>
<div class="line"><a id="l00698" name="l00698"></a><span class="lineno">  698</span><span class="comment"> *         Numeric type.</span></div>
<div class="line"><a id="l00699" name="l00699"></a><span class="lineno">  699</span><span class="comment"> * @tparam Subtrahend</span></div>
<div class="line"><a id="l00700" name="l00700"></a><span class="lineno">  700</span><span class="comment"> *         Numeric type, such that given `Subtrahend s`, `Minuend(s)` is something reasonable for all `s` involved.</span></div>
<div class="line"><a id="l00701" name="l00701"></a><span class="lineno">  701</span><span class="comment"> * @param minuend</span></div>
<div class="line"><a id="l00702" name="l00702"></a><span class="lineno">  702</span><span class="comment"> *        `*minuend` is set to either `(*minuend - subtrahend)` or `floor`, whichever is higher.</span></div>
<div class="line"><a id="l00703" name="l00703"></a><span class="lineno">  703</span><span class="comment"> * @param subtrahend</span></div>
<div class="line"><a id="l00704" name="l00704"></a><span class="lineno">  704</span><span class="comment"> *        Ditto.</span></div>
<div class="line"><a id="l00705" name="l00705"></a><span class="lineno">  705</span><span class="comment"> * @param floor</span></div>
<div class="line"><a id="l00706" name="l00706"></a><span class="lineno">  706</span><span class="comment"> *        Ditto.  Negatives are OK.  Typically it&#39;s best to keep the magnitude of this small.</span></div>
<div class="line"><a id="l00707" name="l00707"></a><span class="lineno">  707</span><span class="comment"> * @return `true` if `*minuend == floor` at function exit; `false` if `*minuend &gt; floor`.</span></div>
<div class="line"><a id="l00708" name="l00708"></a><span class="lineno">  708</span><span class="comment"> */</span></div>
<div class="line"><a id="l00709" name="l00709"></a><span class="lineno">  709</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Minuend, <span class="keyword">typename</span> Subtrahend&gt;</div>
<div class="line"><a id="l00710" name="l00710"></a><span class="lineno">  710</span><span class="keywordtype">bool</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a34ed70fa4de81a4fdb9234bfb5a3a914">subtract_with_floor</a>(Minuend* minuend, <span class="keyword">const</span> Subtrahend&amp; subtrahend, <span class="keyword">const</span> Minuend&amp; floor = 0);</div>
<div class="line"><a id="l00711" name="l00711"></a><span class="lineno">  711</span><span class="comment"></span> </div>
<div class="line"><a id="l00712" name="l00712"></a><span class="lineno">  712</span><span class="comment">/**</span></div>
<div class="line"><a id="l00713" name="l00713"></a><span class="lineno">  713</span><span class="comment"> * Answers the question *what&#39;s the smallest integer number of `To`s sufficient to verbatim store the given number of</span></div>
<div class="line"><a id="l00714" name="l00714"></a><span class="lineno">  714</span><span class="comment"> * `From`s?*, where `From` and `To` are POD types.</span></div>
<div class="line"><a id="l00715" name="l00715"></a><span class="lineno">  715</span><span class="comment"> *</span></div>
<div class="line"><a id="l00716" name="l00716"></a><span class="lineno">  716</span><span class="comment"> * For example, one needs 1 `uint64_t` to store 1, 2, 3, or 4 `uint16_t`s, hence</span></div>
<div class="line"><a id="l00717" name="l00717"></a><span class="lineno">  717</span><span class="comment"> * `size_unit_convert&lt;uint16_t, uint64_t&gt;(1 or 2 or 3 or 4) == 1`.  Similarly, 5 or 6 or 7 or 8 -&gt; 2.</span></div>
<div class="line"><a id="l00718" name="l00718"></a><span class="lineno">  718</span><span class="comment"> * It works in the opposite direction, too; if we are storing `uint64_t`s in multiples of `uint16_t`, then</span></div>
<div class="line"><a id="l00719" name="l00719"></a><span class="lineno">  719</span><span class="comment"> * 1 -&gt; 4, 2 -&gt; 8, 3 -&gt; 12, etc.</span></div>
<div class="line"><a id="l00720" name="l00720"></a><span class="lineno">  720</span><span class="comment"> *</span></div>
<div class="line"><a id="l00721" name="l00721"></a><span class="lineno">  721</span><span class="comment"> * To be clear, when `From` bit width is smaller than `To` bit width, some of the bits will be padding and</span></div>
<div class="line"><a id="l00722" name="l00722"></a><span class="lineno">  722</span><span class="comment"> * presumably unused.  For example, raw data buffers of arbitrary bytes are often arranged in multi-byte &quot;words.&quot;</span></div>
<div class="line"><a id="l00723" name="l00723"></a><span class="lineno">  723</span><span class="comment"> *</span></div>
<div class="line"><a id="l00724" name="l00724"></a><span class="lineno">  724</span><span class="comment"> * @tparam From</span></div>
<div class="line"><a id="l00725" name="l00725"></a><span class="lineno">  725</span><span class="comment"> *         The POD type of the values that must be encoded in `From`s.</span></div>
<div class="line"><a id="l00726" name="l00726"></a><span class="lineno">  726</span><span class="comment"> * @tparam To</span></div>
<div class="line"><a id="l00727" name="l00727"></a><span class="lineno">  727</span><span class="comment"> *         The POD type of the array that would store the `From`s.</span></div>
<div class="line"><a id="l00728" name="l00728"></a><span class="lineno">  728</span><span class="comment"> * @param num_froms</span></div>
<div class="line"><a id="l00729" name="l00729"></a><span class="lineno">  729</span><span class="comment"> *        How many `From`s does one want to encode in an array of `To`s?</span></div>
<div class="line"><a id="l00730" name="l00730"></a><span class="lineno">  730</span><span class="comment"> * @return How many `To`s are sufficient to encode `num_from` `From`s verbatim?</span></div>
<div class="line"><a id="l00731" name="l00731"></a><span class="lineno">  731</span><span class="comment"> */</span></div>
<div class="line"><a id="l00732" name="l00732"></a><span class="lineno">  732</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> From, <span class="keyword">typename</span> To&gt;</div>
<div class="line"><a id="l00733" name="l00733"></a><span class="lineno">  733</span><span class="keywordtype">size_t</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a67eecb5096dabfaff3d02c419b304540">size_unit_convert</a>(From num_froms);</div>
<div class="line"><a id="l00734" name="l00734"></a><span class="lineno">  734</span><span class="comment"></span> </div>
<div class="line"><a id="l00735" name="l00735"></a><span class="lineno">  735</span><span class="comment">/**</span></div>
<div class="line"><a id="l00736" name="l00736"></a><span class="lineno">  736</span><span class="comment"> * Given a generic sequence (integer -&gt; object) generates a generic map (object -&gt; integer) providing inverse</span></div>
<div class="line"><a id="l00737" name="l00737"></a><span class="lineno">  737</span><span class="comment"> * lookup.  See the 3-arg overload if you want to provide a more complex lookup function to store something else based</span></div>
<div class="line"><a id="l00738" name="l00738"></a><span class="lineno">  738</span><span class="comment"> * on each index.</span></div>
<div class="line"><a id="l00739" name="l00739"></a><span class="lineno">  739</span><span class="comment"> *</span></div>
<div class="line"><a id="l00740" name="l00740"></a><span class="lineno">  740</span><span class="comment"> * A naive way of implementing lookups otherwise would be a linear search for the object; using this will</span></div>
<div class="line"><a id="l00741" name="l00741"></a><span class="lineno">  741</span><span class="comment"> * use RAM to avoid the slow searches.</span></div>
<div class="line"><a id="l00742" name="l00742"></a><span class="lineno">  742</span><span class="comment"> *</span></div>
<div class="line"><a id="l00743" name="l00743"></a><span class="lineno">  743</span><span class="comment"> * @tparam Sequence</span></div>
<div class="line"><a id="l00744" name="l00744"></a><span class="lineno">  744</span><span class="comment"> *         Sequence such as `std::vector&lt;T&gt;` or `std::array&lt;T&gt;`.</span></div>
<div class="line"><a id="l00745" name="l00745"></a><span class="lineno">  745</span><span class="comment"> *         Informally, `T` should be something light-weight and hence usable as a key type for a map type (`Map`).</span></div>
<div class="line"><a id="l00746" name="l00746"></a><span class="lineno">  746</span><span class="comment"> * @tparam Map</span></div>
<div class="line"><a id="l00747" name="l00747"></a><span class="lineno">  747</span><span class="comment"> *         Map that maps `T` from `Sequence` to `size_t`.  Example: `std::map&lt;T, size_t&gt;`.</span></div>
<div class="line"><a id="l00748" name="l00748"></a><span class="lineno">  748</span><span class="comment"> * @param src_seq</span></div>
<div class="line"><a id="l00749" name="l00749"></a><span class="lineno">  749</span><span class="comment"> *        Input sequence.</span></div>
<div class="line"><a id="l00750" name="l00750"></a><span class="lineno">  750</span><span class="comment"> * @param target_map</span></div>
<div class="line"><a id="l00751" name="l00751"></a><span class="lineno">  751</span><span class="comment"> *        Output map.  Note it will *not* be pre-cleared; informally, this means one can shove 2+ lookup maps</span></div>
<div class="line"><a id="l00752" name="l00752"></a><span class="lineno">  752</span><span class="comment"> *        into one.  If null behavior undefined (assertion may trip).</span></div>
<div class="line"><a id="l00753" name="l00753"></a><span class="lineno">  753</span><span class="comment"> */</span></div>
<div class="line"><a id="l00754" name="l00754"></a><span class="lineno">  754</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Map, <span class="keyword">typename</span> Sequence&gt;</div>
<div class="line"><a id="l00755" name="l00755"></a><span class="lineno">  755</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a0a873d1abeac7a29822e940adf4f06c9">sequence_to_inverted_lookup_map</a>(Sequence <span class="keyword">const</span> &amp; src_seq, Map* target_map);</div>
<div class="line"><a id="l00756" name="l00756"></a><span class="lineno">  756</span><span class="comment"></span> </div>
<div class="line"><a id="l00757" name="l00757"></a><span class="lineno">  757</span><span class="comment">/**</span></div>
<div class="line"><a id="l00758" name="l00758"></a><span class="lineno">  758</span><span class="comment"> * Similar to the 2-arg overload of sequence_to_inverted_lookup_map() but with the ability to store a value based</span></div>
<div class="line"><a id="l00759" name="l00759"></a><span class="lineno">  759</span><span class="comment"> * on the index into the input sequence instead of that index itself.  See the 2-arg overload.</span></div>
<div class="line"><a id="l00760" name="l00760"></a><span class="lineno">  760</span><span class="comment"> *</span></div>
<div class="line"><a id="l00761" name="l00761"></a><span class="lineno">  761</span><span class="comment"> * @tparam Sequence</span></div>
<div class="line"><a id="l00762" name="l00762"></a><span class="lineno">  762</span><span class="comment"> *         Sequence such as `std::vector&lt;T&gt;` or `std::array&lt;T&gt;`.</span></div>
<div class="line"><a id="l00763" name="l00763"></a><span class="lineno">  763</span><span class="comment"> *         Informally, `T` should be something light-weight and hence usable as a key type for a map type (`Map`).</span></div>
<div class="line"><a id="l00764" name="l00764"></a><span class="lineno">  764</span><span class="comment"> * @tparam Map</span></div>
<div class="line"><a id="l00765" name="l00765"></a><span class="lineno">  765</span><span class="comment"> *         Map that maps `T` from `Sequence` to another type `X`.  Example:</span></div>
<div class="line"><a id="l00766" name="l00766"></a><span class="lineno">  766</span><span class="comment"> *         `unordered_map&lt;T, X&gt;`, where an `X` can be computed from a `size_t` index.</span></div>
<div class="line"><a id="l00767" name="l00767"></a><span class="lineno">  767</span><span class="comment"> * @param src_seq</span></div>
<div class="line"><a id="l00768" name="l00768"></a><span class="lineno">  768</span><span class="comment"> *        See 2-arg overload.</span></div>
<div class="line"><a id="l00769" name="l00769"></a><span class="lineno">  769</span><span class="comment"> * @param target_map</span></div>
<div class="line"><a id="l00770" name="l00770"></a><span class="lineno">  770</span><span class="comment"> *        See 2-arg overload.</span></div>
<div class="line"><a id="l00771" name="l00771"></a><span class="lineno">  771</span><span class="comment"> * @param idx_to_map_val_func</span></div>
<div class="line"><a id="l00772" name="l00772"></a><span class="lineno">  772</span><span class="comment"> *        Given an index `idx` into `src_seq`, `(*target_map)[]` shall contain `idx_to_map_val_func(idx)`.</span></div>
<div class="line"><a id="l00773" name="l00773"></a><span class="lineno">  773</span><span class="comment"> *        Use this arg to instead perform a second lookup before storing a value in `*target_map`.</span></div>
<div class="line"><a id="l00774" name="l00774"></a><span class="lineno">  774</span><span class="comment"> *        Use the 2-arg overload if you&#39;d like to store the index itself.</span></div>
<div class="line"><a id="l00775" name="l00775"></a><span class="lineno">  775</span><span class="comment"> */</span></div>
<div class="line"><a id="l00776" name="l00776"></a><span class="lineno">  776</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Map, <span class="keyword">typename</span> Sequence&gt;</div>
<div class="line"><a id="l00777" name="l00777"></a><span class="lineno">  777</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a0a873d1abeac7a29822e940adf4f06c9">sequence_to_inverted_lookup_map</a></div>
<div class="line"><a id="l00778" name="l00778"></a><span class="lineno">  778</span>       (Sequence <span class="keyword">const</span> &amp; src_seq, Map* target_map,</div>
<div class="line"><a id="l00779" name="l00779"></a><span class="lineno">  779</span>        <span class="keyword">const</span> <a class="code hl_class" href="classflow_1_1Function.html">Function</a>&lt;<span class="keyword">typename</span> Map::mapped_type (<span class="keywordtype">size_t</span>)&gt;&amp; idx_to_map_val_func);</div>
<div class="line"><a id="l00780" name="l00780"></a><span class="lineno">  780</span><span class="comment"></span> </div>
<div class="line"><a id="l00781" name="l00781"></a><span class="lineno">  781</span><span class="comment">/**</span></div>
<div class="line"><a id="l00782" name="l00782"></a><span class="lineno">  782</span><span class="comment"> * Writes to the specified string, as if the given arguments were each passed, via `&lt;&lt;` in sequence,</span></div>
<div class="line"><a id="l00783" name="l00783"></a><span class="lineno">  783</span><span class="comment"> * to an `ostringstream`, and then the result were appended to the aforementioned string variable.</span></div>
<div class="line"><a id="l00784" name="l00784"></a><span class="lineno">  784</span><span class="comment"> *</span></div>
<div class="line"><a id="l00785" name="l00785"></a><span class="lineno">  785</span><span class="comment"> * Tip: It works nicely, 99% as nicely as simply `&lt;&lt;`ing an `ostream`; but certain language subtleties mean</span></div>
<div class="line"><a id="l00786" name="l00786"></a><span class="lineno">  786</span><span class="comment"> * you may have to fully qualify some template instances among `ostream_args`.  Do so if you receive a</span></div>
<div class="line"><a id="l00787" name="l00787"></a><span class="lineno">  787</span><span class="comment"> * &quot;deduced incomplete pack&quot; (clang) or similar error, as I have seen when using, e.g., `chrono::symbol_format`</span></div>
<div class="line"><a id="l00788" name="l00788"></a><span class="lineno">  788</span><span class="comment"> * formatter (which the compile error forced me to qualify as: `symbol_format&lt;char, ostream::traits_type&gt;`).</span></div>
<div class="line"><a id="l00789" name="l00789"></a><span class="lineno">  789</span><span class="comment"> *</span></div>
<div class="line"><a id="l00790" name="l00790"></a><span class="lineno">  790</span><span class="comment"> * @see log::Thread_local_string_appender for an even more efficient version of this for some applications that can</span></div>
<div class="line"><a id="l00791" name="l00791"></a><span class="lineno">  791</span><span class="comment"> *      also enable a continuous stream across multiple stream-writing statements over time.</span></div>
<div class="line"><a id="l00792" name="l00792"></a><span class="lineno">  792</span><span class="comment"> *</span></div>
<div class="line"><a id="l00793" name="l00793"></a><span class="lineno">  793</span><span class="comment"> * @tparam ...T</span></div>
<div class="line"><a id="l00794" name="l00794"></a><span class="lineno">  794</span><span class="comment"> *         Each type `T` is such that `os &lt;&lt; t`, with types `T const &amp; t` and `ostream&amp; os`, builds and writes</span></div>
<div class="line"><a id="l00795" name="l00795"></a><span class="lineno">  795</span><span class="comment"> *         `t` to `os`, returning lvalue `os`.</span></div>
<div class="line"><a id="l00796" name="l00796"></a><span class="lineno">  796</span><span class="comment"> *         Usually in practice this means the existence of `ostream&amp; operator&lt;&lt;(ostream&amp;, T const &amp;)` or</span></div>
<div class="line"><a id="l00797" name="l00797"></a><span class="lineno">  797</span><span class="comment"> *         `ostream&amp; operator&lt;&lt;(ostream&amp;, T)` overload, the latter usually for basic types `T`.</span></div>
<div class="line"><a id="l00798" name="l00798"></a><span class="lineno">  798</span><span class="comment"> *         See also tip above, if compiler is unable to deduce a given `T` (even when it *would* deduce it</span></div>
<div class="line"><a id="l00799" name="l00799"></a><span class="lineno">  799</span><span class="comment"> *         in `os &lt;&lt; t`).</span></div>
<div class="line"><a id="l00800" name="l00800"></a><span class="lineno">  800</span><span class="comment"> * @param target_str</span></div>
<div class="line"><a id="l00801" name="l00801"></a><span class="lineno">  801</span><span class="comment"> *        Pointer to the string to which to append.</span></div>
<div class="line"><a id="l00802" name="l00802"></a><span class="lineno">  802</span><span class="comment"> * @param ostream_args</span></div>
<div class="line"><a id="l00803" name="l00803"></a><span class="lineno">  803</span><span class="comment"> *        One or more arguments, such that each argument `arg` is suitable for `os &lt;&lt; arg`, where</span></div>
<div class="line"><a id="l00804" name="l00804"></a><span class="lineno">  804</span><span class="comment"> *        `os` is an `ostream`.</span></div>
<div class="line"><a id="l00805" name="l00805"></a><span class="lineno">  805</span><span class="comment"> */</span></div>
<div class="line"><a id="l00806" name="l00806"></a><span class="lineno">  806</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> ...T&gt;</div>
<div class="line"><a id="l00807" name="l00807"></a><span class="lineno">  807</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a8afd30c50bcd670d45442df49d1da484">ostream_op_to_string</a>(std::string* target_str, T <span class="keyword">const</span> &amp;... ostream_args);</div>
<div class="line"><a id="l00808" name="l00808"></a><span class="lineno">  808</span><span class="comment"></span> </div>
<div class="line"><a id="l00809" name="l00809"></a><span class="lineno">  809</span><span class="comment">/**</span></div>
<div class="line"><a id="l00810" name="l00810"></a><span class="lineno">  810</span><span class="comment"> * Equivalent to ostream_op_to_string() but returns a new `string` by value instead of writing to the caller&#39;s</span></div>
<div class="line"><a id="l00811" name="l00811"></a><span class="lineno">  811</span><span class="comment"> * `string`.  This is useful at least in constructor initializers, where it is not possible to first</span></div>
<div class="line"><a id="l00812" name="l00812"></a><span class="lineno">  812</span><span class="comment"> * declare a stack variable.</span></div>
<div class="line"><a id="l00813" name="l00813"></a><span class="lineno">  813</span><span class="comment"> *</span></div>
<div class="line"><a id="l00814" name="l00814"></a><span class="lineno">  814</span><span class="comment"> * With the C++11-y use of move semantics in STL it should be no slower than using</span></div>
<div class="line"><a id="l00815" name="l00815"></a><span class="lineno">  815</span><span class="comment"> * `ostream_op_to_string()` -- meaning, it is no slower, period, as this library now requires C++11.</span></div>
<div class="line"><a id="l00816" name="l00816"></a><span class="lineno">  816</span><span class="comment"> *</span></div>
<div class="line"><a id="l00817" name="l00817"></a><span class="lineno">  817</span><span class="comment"> * @tparam ...T</span></div>
<div class="line"><a id="l00818" name="l00818"></a><span class="lineno">  818</span><span class="comment"> *         See ostream_op_to_string().</span></div>
<div class="line"><a id="l00819" name="l00819"></a><span class="lineno">  819</span><span class="comment"> * @param ostream_args</span></div>
<div class="line"><a id="l00820" name="l00820"></a><span class="lineno">  820</span><span class="comment"> *        See ostream_op_to_string().</span></div>
<div class="line"><a id="l00821" name="l00821"></a><span class="lineno">  821</span><span class="comment"> * @return Resulting `std::string`.</span></div>
<div class="line"><a id="l00822" name="l00822"></a><span class="lineno">  822</span><span class="comment"> */</span></div>
<div class="line"><a id="l00823" name="l00823"></a><span class="lineno">  823</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> ...T&gt;</div>
<div class="line"><a id="l00824" name="l00824"></a><span class="lineno">  824</span>std::string <a class="code hl_function" href="namespaceflow_1_1util.html#a685b86585da2fa5186f51854e7ae1561">ostream_op_string</a>(T <span class="keyword">const</span> &amp;... ostream_args);</div>
<div class="line"><a id="l00825" name="l00825"></a><span class="lineno">  825</span><span class="comment"></span> </div>
<div class="line"><a id="l00826" name="l00826"></a><span class="lineno">  826</span><span class="comment">/**</span></div>
<div class="line"><a id="l00827" name="l00827"></a><span class="lineno">  827</span><span class="comment"> * &quot;Induction step&quot; version of variadic function template that simply outputs arguments 2+ via</span></div>
<div class="line"><a id="l00828" name="l00828"></a><span class="lineno">  828</span><span class="comment"> * `&lt;&lt;` to the given `ostream`, in the order given.</span></div>
<div class="line"><a id="l00829" name="l00829"></a><span class="lineno">  829</span><span class="comment"> *</span></div>
<div class="line"><a id="l00830" name="l00830"></a><span class="lineno">  830</span><span class="comment"> * @tparam ...T_rest</span></div>
<div class="line"><a id="l00831" name="l00831"></a><span class="lineno">  831</span><span class="comment"> *         See `...T` in ostream_op_to_string().</span></div>
<div class="line"><a id="l00832" name="l00832"></a><span class="lineno">  832</span><span class="comment"> * @param remaining_ostream_args</span></div>
<div class="line"><a id="l00833" name="l00833"></a><span class="lineno">  833</span><span class="comment"> *        See `ostream_args` in ostream_op_to_string().</span></div>
<div class="line"><a id="l00834" name="l00834"></a><span class="lineno">  834</span><span class="comment"> * @tparam T1</span></div>
<div class="line"><a id="l00835" name="l00835"></a><span class="lineno">  835</span><span class="comment"> *         Same as each of `...T_rest`.</span></div>
<div class="line"><a id="l00836" name="l00836"></a><span class="lineno">  836</span><span class="comment"> * @param ostream_arg1</span></div>
<div class="line"><a id="l00837" name="l00837"></a><span class="lineno">  837</span><span class="comment"> *        Same as each of `remaining_ostream_args`.</span></div>
<div class="line"><a id="l00838" name="l00838"></a><span class="lineno">  838</span><span class="comment"> * @param os</span></div>
<div class="line"><a id="l00839" name="l00839"></a><span class="lineno">  839</span><span class="comment"> *        Pointer to stream to which to sequentially send arguments for output.</span></div>
<div class="line"><a id="l00840" name="l00840"></a><span class="lineno">  840</span><span class="comment"> */</span></div>
<div class="line"><a id="l00841" name="l00841"></a><span class="lineno">  841</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T1, <span class="keyword">typename</span> ...T_rest&gt;</div>
<div class="line"><a id="l00842" name="l00842"></a><span class="lineno">  842</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#af92e6183c2071f4166d4b5a91f50d70c">feed_args_to_ostream</a>(std::ostream* os, T1 <span class="keyword">const</span> &amp; ostream_arg1, T_rest <span class="keyword">const</span> &amp;... remaining_ostream_args);</div>
<div class="line"><a id="l00843" name="l00843"></a><span class="lineno">  843</span><span class="comment"></span> </div>
<div class="line"><a id="l00844" name="l00844"></a><span class="lineno">  844</span><span class="comment">/**</span></div>
<div class="line"><a id="l00845" name="l00845"></a><span class="lineno">  845</span><span class="comment"> * &quot;Induction base&quot; for a variadic function template, this simply outputs given item to given `ostream` via `&lt;&lt;`.</span></div>
<div class="line"><a id="l00846" name="l00846"></a><span class="lineno">  846</span><span class="comment"> *</span></div>
<div class="line"><a id="l00847" name="l00847"></a><span class="lineno">  847</span><span class="comment"> * @tparam T</span></div>
<div class="line"><a id="l00848" name="l00848"></a><span class="lineno">  848</span><span class="comment"> *         See each of `...T` in ostream_op_to_string().</span></div>
<div class="line"><a id="l00849" name="l00849"></a><span class="lineno">  849</span><span class="comment"> * @param os</span></div>
<div class="line"><a id="l00850" name="l00850"></a><span class="lineno">  850</span><span class="comment"> *        Pointer to stream to which to sequentially send arguments for output.</span></div>
<div class="line"><a id="l00851" name="l00851"></a><span class="lineno">  851</span><span class="comment"> * @param only_ostream_arg</span></div>
<div class="line"><a id="l00852" name="l00852"></a><span class="lineno">  852</span><span class="comment"> *        See each of `ostream_args` in ostream_op_to_string().</span></div>
<div class="line"><a id="l00853" name="l00853"></a><span class="lineno">  853</span><span class="comment"> */</span></div>
<div class="line"><a id="l00854" name="l00854"></a><span class="lineno">  854</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> T&gt;</div>
<div class="line"><a id="l00855" name="l00855"></a><span class="lineno">  855</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#af92e6183c2071f4166d4b5a91f50d70c">feed_args_to_ostream</a>(std::ostream* os, T <span class="keyword">const</span> &amp; only_ostream_arg);</div>
<div class="line"><a id="l00856" name="l00856"></a><span class="lineno">  856</span><span class="comment"></span> </div>
<div class="line"><a id="l00857" name="l00857"></a><span class="lineno">  857</span><span class="comment">/**</span></div>
<div class="line"><a id="l00858" name="l00858"></a><span class="lineno">  858</span><span class="comment"> * Deserializes an `enum class` value from a standard input stream.  Reads up to but not including the next</span></div>
<div class="line"><a id="l00859" name="l00859"></a><span class="lineno">  859</span><span class="comment"> * non-alphanumeric-or-underscore character; the resulting string is then mapped to an `Enum`.  If none is</span></div>
<div class="line"><a id="l00860" name="l00860"></a><span class="lineno">  860</span><span class="comment"> * recognized, `enum_default` is the result.  The recognized values are:</span></div>
<div class="line"><a id="l00861" name="l00861"></a><span class="lineno">  861</span><span class="comment"> *   - &quot;0&quot;, &quot;1&quot;, ...: Corresponds to the underlying-integer conversion to that `Enum`.  (Can be disabled optionally.)</span></div>
<div class="line"><a id="l00862" name="l00862"></a><span class="lineno">  862</span><span class="comment"> *   - Case-[in]sensitive string encoding of the `Enum`, as determined by `operator&lt;&lt;(ostream&amp;)` -- which must exist</span></div>
<div class="line"><a id="l00863" name="l00863"></a><span class="lineno">  863</span><span class="comment"> *     (or this will not compile).  Informally we recommend the encoding to be the non-S_-prefix part of the actual</span></div>
<div class="line"><a id="l00864" name="l00864"></a><span class="lineno">  864</span><span class="comment"> *     `Enum` member; e.g., `&quot;WARNING&quot;` for log::Sev::S_WARNING.</span></div>
<div class="line"><a id="l00865" name="l00865"></a><span class="lineno">  865</span><span class="comment"> * If the scanned token does not map to any of these, or if end-of-input is encountered immediately (empty token),</span></div>
<div class="line"><a id="l00866" name="l00866"></a><span class="lineno">  866</span><span class="comment"> * then `enum_default` is returned.</span></div>
<div class="line"><a id="l00867" name="l00867"></a><span class="lineno">  867</span><span class="comment"> *</span></div>
<div class="line"><a id="l00868" name="l00868"></a><span class="lineno">  868</span><span class="comment"> * Error semantics: There are no invalid values or exceptions thrown; `enum_default` returned is the worst case.</span></div>
<div class="line"><a id="l00869" name="l00869"></a><span class="lineno">  869</span><span class="comment"> * Do note `*is_ptr` may not be `good() == true` after return.</span></div>
<div class="line"><a id="l00870" name="l00870"></a><span class="lineno">  870</span><span class="comment"> *</span></div>
<div class="line"><a id="l00871" name="l00871"></a><span class="lineno">  871</span><span class="comment"> * Tip: It is convenient to implement `operator&gt;&gt;(istream&amp;)` in terms of istream_to_enum().  With both</span></div>
<div class="line"><a id="l00872" name="l00872"></a><span class="lineno">  872</span><span class="comment"> * `&gt;&gt;` and `&lt;&lt;` available, serialization/deserialization of the `enum class` will work; this enables a few key things</span></div>
<div class="line"><a id="l00873" name="l00873"></a><span class="lineno">  873</span><span class="comment"> * to work, including parsing from config file/command line via and conversion from `string` via `lexical_cast`.</span></div>
<div class="line"><a id="l00874" name="l00874"></a><span class="lineno">  874</span><span class="comment"> *</span></div>
<div class="line"><a id="l00875" name="l00875"></a><span class="lineno">  875</span><span class="comment"> * Informal convention suggestion: `S_END_SENTINEL` should be the sentinel member of `Enum`.  E.g., see log::Sev.</span></div>
<div class="line"><a id="l00876" name="l00876"></a><span class="lineno">  876</span><span class="comment"> *</span></div>
<div class="line"><a id="l00877" name="l00877"></a><span class="lineno">  877</span><span class="comment"> * @tparam Enum</span></div>
<div class="line"><a id="l00878" name="l00878"></a><span class="lineno">  878</span><span class="comment"> *         An `enum class` which must satisfy the following requirements or else risk undefined behavior (if it</span></div>
<div class="line"><a id="l00879" name="l00879"></a><span class="lineno">  879</span><span class="comment"> *         compiles): An element, `enum_lowest`, has a non-negative integer value.</span></div>
<div class="line"><a id="l00880" name="l00880"></a><span class="lineno">  880</span><span class="comment"> *         Subsequent elements are strictly monotonically increasing with increment 1, up to and including</span></div>
<div class="line"><a id="l00881" name="l00881"></a><span class="lineno">  881</span><span class="comment"> *         `enum_sentinel`.  (Elements outside [`enum_lowest`, `enum_sentinel`] may exist, as long as their numeric</span></div>
<div class="line"><a id="l00882" name="l00882"></a><span class="lineno">  882</span><span class="comment"> *         values don&#39;t conflict with those in-range, but informally we recommend against this.)</span></div>
<div class="line"><a id="l00883" name="l00883"></a><span class="lineno">  883</span><span class="comment"> *         `ostream &lt;&lt; Enum` exists and works without throwing for all values in range</span></div>
<div class="line"><a id="l00884" name="l00884"></a><span class="lineno">  884</span><span class="comment"> *         [`enum_lowest`, `enum_sentinel`).  Each `&lt;&lt;`-serialized string must be distinct from the others.</span></div>
<div class="line"><a id="l00885" name="l00885"></a><span class="lineno">  885</span><span class="comment"> *         Each `&lt;&lt;`-serialized string must start with a non-digit and must consist only of alphanumerics and</span></div>
<div class="line"><a id="l00886" name="l00886"></a><span class="lineno">  886</span><span class="comment"> *         underscores.  Exception: digit-leading is allowed if and only if `!accept_num_encoding`, though</span></div>
<div class="line"><a id="l00887" name="l00887"></a><span class="lineno">  887</span><span class="comment"> *         informally we recommend against it as a convention.</span></div>
<div class="line"><a id="l00888" name="l00888"></a><span class="lineno">  888</span><span class="comment"> *</span></div>
<div class="line"><a id="l00889" name="l00889"></a><span class="lineno">  889</span><span class="comment"> * @param is_ptr</span></div>
<div class="line"><a id="l00890" name="l00890"></a><span class="lineno">  890</span><span class="comment"> *        Stream from which to deserialize.</span></div>
<div class="line"><a id="l00891" name="l00891"></a><span class="lineno">  891</span><span class="comment"> * @param enum_default</span></div>
<div class="line"><a id="l00892" name="l00892"></a><span class="lineno">  892</span><span class="comment"> *        Value to return if the token does not match either the numeric encoding (if enabled) or the `&lt;&lt;` encoding.</span></div>
<div class="line"><a id="l00893" name="l00893"></a><span class="lineno">  893</span><span class="comment"> *        `enum_sentinel` is a sensible (but not the only sensible) choice.</span></div>
<div class="line"><a id="l00894" name="l00894"></a><span class="lineno">  894</span><span class="comment"> * @param enum_sentinel</span></div>
<div class="line"><a id="l00895" name="l00895"></a><span class="lineno">  895</span><span class="comment"> *        `Enum` value such that all valid deserializable values have numeric conversions strictly lower than it.</span></div>
<div class="line"><a id="l00896" name="l00896"></a><span class="lineno">  896</span><span class="comment"> * @param accept_num_encoding</span></div>
<div class="line"><a id="l00897" name="l00897"></a><span class="lineno">  897</span><span class="comment"> *        If `true`, a numeric value is accepted as an encoding; otherwise it is not (and will yield `enum_default`</span></div>
<div class="line"><a id="l00898" name="l00898"></a><span class="lineno">  898</span><span class="comment"> *        like any other non-matching token).</span></div>
<div class="line"><a id="l00899" name="l00899"></a><span class="lineno">  899</span><span class="comment"> * @param case_sensitive</span></div>
<div class="line"><a id="l00900" name="l00900"></a><span class="lineno">  900</span><span class="comment"> *        If `true`, then the token must exactly equal an `ostream&lt;&lt;` encoding of a non-sentinel `Enum`;</span></div>
<div class="line"><a id="l00901" name="l00901"></a><span class="lineno">  901</span><span class="comment"> *        otherwise it may equal it modulo different case.</span></div>
<div class="line"><a id="l00902" name="l00902"></a><span class="lineno">  902</span><span class="comment"> * @param enum_lowest</span></div>
<div class="line"><a id="l00903" name="l00903"></a><span class="lineno">  903</span><span class="comment"> *        The lowest `Enum` value.  Its integer value is very often 0, sometimes 1.</span></div>
<div class="line"><a id="l00904" name="l00904"></a><span class="lineno">  904</span><span class="comment"> *        Behavior undefined if it is negative.</span></div>
<div class="line"><a id="l00905" name="l00905"></a><span class="lineno">  905</span><span class="comment"> * @return See above.</span></div>
<div class="line"><a id="l00906" name="l00906"></a><span class="lineno">  906</span><span class="comment"> */</span></div>
<div class="line"><a id="l00907" name="l00907"></a><span class="lineno">  907</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Enum&gt;</div>
<div class="line"><a id="l00908" name="l00908"></a><span class="lineno">  908</span>Enum <a class="code hl_function" href="namespaceflow_1_1util.html#a18a29d6a6e65c3b96c52b5cad5971266">istream_to_enum</a>(std::istream* is_ptr, Enum enum_default, Enum enum_sentinel,</div>
<div class="line"><a id="l00909" name="l00909"></a><span class="lineno">  909</span>                     <span class="keywordtype">bool</span> accept_num_encoding = <span class="keyword">true</span>, <span class="keywordtype">bool</span> case_sensitive = <span class="keyword">false</span>,</div>
<div class="line"><a id="l00910" name="l00910"></a><span class="lineno">  910</span>                     Enum enum_lowest = Enum(0));</div>
<div class="line"><a id="l00911" name="l00911"></a><span class="lineno">  911</span><span class="comment"></span> </div>
<div class="line"><a id="l00912" name="l00912"></a><span class="lineno">  912</span><span class="comment">/**</span></div>
<div class="line"><a id="l00913" name="l00913"></a><span class="lineno">  913</span><span class="comment"> * Sets certain `chrono`-related formatting on the given `ostream` that results in a consistent, desirable output</span></div>
<div class="line"><a id="l00914" name="l00914"></a><span class="lineno">  914</span><span class="comment"> * of `duration`s and certain types of `time_point`s.  As of this writing this includes enabling short unit format</span></div>
<div class="line"><a id="l00915" name="l00915"></a><span class="lineno">  915</span><span class="comment"> * (e.g., &quot;ms&quot; instead of &quot;milliseconds&quot;) and avoiding Unicode characters (the Greek letter for micro becomes</span></div>
<div class="line"><a id="l00916" name="l00916"></a><span class="lineno">  916</span><span class="comment"> * a similar-looking &quot;u&quot; instead).</span></div>
<div class="line"><a id="l00917" name="l00917"></a><span class="lineno">  917</span><span class="comment"> *</span></div>
<div class="line"><a id="l00918" name="l00918"></a><span class="lineno">  918</span><span class="comment"> * @see log::beautify_chrono_logger_this_thread() to affect a Logger directly.</span></div>
<div class="line"><a id="l00919" name="l00919"></a><span class="lineno">  919</span><span class="comment"> * @see flow::async in which new threads are set to use this formatting automatically.  However you&#39;ll want to</span></div>
<div class="line"><a id="l00920" name="l00920"></a><span class="lineno">  920</span><span class="comment"> *      do this explicitly for the startup thread.</span></div>
<div class="line"><a id="l00921" name="l00921"></a><span class="lineno">  921</span><span class="comment"> *</span></div>
<div class="line"><a id="l00922" name="l00922"></a><span class="lineno">  922</span><span class="comment"> * @param os</span></div>
<div class="line"><a id="l00923" name="l00923"></a><span class="lineno">  923</span><span class="comment"> *        The stream to affect.</span></div>
<div class="line"><a id="l00924" name="l00924"></a><span class="lineno">  924</span><span class="comment"> */</span></div>
<div class="line"><a id="l00925" name="l00925"></a><span class="lineno">  925</span><span class="keywordtype">void</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a0955a29930075ac1fe393896c089b911">beautify_chrono_ostream</a>(std::ostream* os);</div>
<div class="line"><a id="l00926" name="l00926"></a><span class="lineno">  926</span><span class="comment"></span> </div>
<div class="line"><a id="l00927" name="l00927"></a><span class="lineno">  927</span><span class="comment">/**</span></div>
<div class="line"><a id="l00928" name="l00928"></a><span class="lineno">  928</span><span class="comment"> * Estimate of memory footprint of the given value, including memory allocated on its behalf -- but</span></div>
<div class="line"><a id="l00929" name="l00929"></a><span class="lineno">  929</span><span class="comment"> * excluding its shallow `sizeof`! -- in bytes.</span></div>
<div class="line"><a id="l00930" name="l00930"></a><span class="lineno">  930</span><span class="comment"> *</span></div>
<div class="line"><a id="l00931" name="l00931"></a><span class="lineno">  931</span><span class="comment"> * @param val</span></div>
<div class="line"><a id="l00932" name="l00932"></a><span class="lineno">  932</span><span class="comment"> *        Value.</span></div>
<div class="line"><a id="l00933" name="l00933"></a><span class="lineno">  933</span><span class="comment"> * @return See above.</span></div>
<div class="line"><a id="l00934" name="l00934"></a><span class="lineno">  934</span><span class="comment"> */</span></div>
<div class="line"><a id="l00935" name="l00935"></a><span class="lineno">  935</span><span class="keywordtype">size_t</span> <a class="code hl_function" href="namespaceflow_1_1util.html#a418b56a178c07100eef78da5c9d6ee7a">deep_size</a>(<span class="keyword">const</span> std::string&amp; val);</div>
<div class="line"><a id="l00936" name="l00936"></a><span class="lineno">  936</span> </div>
<div class="line"><a id="l00937" name="l00937"></a><span class="lineno">  937</span><span class="comment">// Macros.</span></div>
<div class="line"><a id="l00938" name="l00938"></a><span class="lineno">  938</span><span class="comment"></span> </div>
<div class="line"><a id="l00939" name="l00939"></a><span class="lineno">  939</span><span class="comment">/**</span></div>
<div class="line"><a id="l00940" name="l00940"></a><span class="lineno">  940</span><span class="comment"> * Expands to an `ostream` fragment `X` (suitable for, for example: `std::cout &lt;&lt; X &lt;&lt; &quot;: Hi!&quot;`) containing</span></div>
<div class="line"><a id="l00941" name="l00941"></a><span class="lineno">  941</span><span class="comment"> * the file name, function name, and line number at the macro invocation&#39;s context.</span></div>
<div class="line"><a id="l00942" name="l00942"></a><span class="lineno">  942</span><span class="comment"> *</span></div>
<div class="line"><a id="l00943" name="l00943"></a><span class="lineno">  943</span><span class="comment"> * It&#39;s a functional macro despite taking no arguments to convey that it mimics a free function sans args.</span></div>
<div class="line"><a id="l00944" name="l00944"></a><span class="lineno">  944</span><span class="comment"> *</span></div>
<div class="line"><a id="l00945" name="l00945"></a><span class="lineno">  945</span><span class="comment"> * @internal</span></div>
<div class="line"><a id="l00946" name="l00946"></a><span class="lineno">  946</span><span class="comment"> *</span></div>
<div class="line"><a id="l00947" name="l00947"></a><span class="lineno">  947</span><span class="comment"> * ### Performance ###</span></div>
<div class="line"><a id="l00948" name="l00948"></a><span class="lineno">  948</span><span class="comment"> * The items `&lt;&lt;`ed onto the target `ostream` are each evaluated at compile-time.</span></div>
<div class="line"><a id="l00949" name="l00949"></a><span class="lineno">  949</span><span class="comment"> * This includes the expression involving flow::util::get_last_path_segment() which is `constexpr`.</span></div>
<div class="line"><a id="l00950" name="l00950"></a><span class="lineno">  950</span><span class="comment"> */</span></div>
<div class="line"><a id="l00951" name="l00951"></a><span class="lineno"><a class="line" href="util__fwd_8hpp.html#a4b8c54b789ea3bbc1dedebbff084625c">  951</a></span><span class="preprocessor">#define FLOW_UTIL_WHERE_AM_I() \</span></div>
<div class="line"><a id="l00952" name="l00952"></a><span class="lineno">  952</span><span class="preprocessor">  FLOW_UTIL_WHERE_AM_I_FROM_ARGS(::flow::util::get_last_path_segment \</span></div>
<div class="line"><a id="l00953" name="l00953"></a><span class="lineno">  953</span><span class="preprocessor">                                   (::flow::util::String_view(__FILE__, sizeof(__FILE__) - 1)), \</span></div>
<div class="line"><a id="l00954" name="l00954"></a><span class="lineno">  954</span><span class="preprocessor">                                 ::flow::util::String_view(__FUNCTION__, sizeof(__FUNCTION__) - 1), \</span></div>
<div class="line"><a id="l00955" name="l00955"></a><span class="lineno">  955</span><span class="preprocessor">                                 __LINE__)</span></div>
<div class="line"><a id="l00956" name="l00956"></a><span class="lineno">  956</span><span class="comment"></span> </div>
<div class="line"><a id="l00957" name="l00957"></a><span class="lineno">  957</span><span class="comment">/**</span></div>
<div class="line"><a id="l00958" name="l00958"></a><span class="lineno">  958</span><span class="comment"> * Same as FLOW_UTIL_WHERE_AM_I() but evaluates to an `std::string`.  It&#39;s probably a bit slower as</span></div>
<div class="line"><a id="l00959" name="l00959"></a><span class="lineno">  959</span><span class="comment"> * well.  Update: In fact, it&#39;s probably significantly slower as of this writing, as</span></div>
<div class="line"><a id="l00960" name="l00960"></a><span class="lineno">  960</span><span class="comment"> * FLOW_UTIL_WHERE_AM_I() evaluates the `&lt;&lt;`ed items at compile-time, while this cannot due to how it&#39;s implemented.</span></div>
<div class="line"><a id="l00961" name="l00961"></a><span class="lineno">  961</span><span class="comment"> *</span></div>
<div class="line"><a id="l00962" name="l00962"></a><span class="lineno">  962</span><span class="comment"> * @internal</span></div>
<div class="line"><a id="l00963" name="l00963"></a><span class="lineno">  963</span><span class="comment"> *</span></div>
<div class="line"><a id="l00964" name="l00964"></a><span class="lineno">  964</span><span class="comment"> * flow::util::get_where_am_i_str() is too clever to become a `constexpr` function, even if it were radically rewritten,</span></div>
<div class="line"><a id="l00965" name="l00965"></a><span class="lineno">  965</span><span class="comment"> * so this macro evaluates to a partially runtime-computed expression.  Hence the note just above about perf.</span></div>
<div class="line"><a id="l00966" name="l00966"></a><span class="lineno">  966</span><span class="comment"> *</span></div>
<div class="line"><a id="l00967" name="l00967"></a><span class="lineno">  967</span><span class="comment"> * @todo See if FLOW_UTIL_WHERE_AM_I_STR() can be coaxed into a compile-time expression after all.  It is used in</span></div>
<div class="line"><a id="l00968" name="l00968"></a><span class="lineno">  968</span><span class="comment"> * quite a lot of frequently executed code, namely at the top of most Flow (and Flow-like) APIs that can emit errors.</span></div>
<div class="line"><a id="l00969" name="l00969"></a><span class="lineno">  969</span><span class="comment"> * See notes inside flow::util::get_where_am_i_str() on this as of this writing.</span></div>
<div class="line"><a id="l00970" name="l00970"></a><span class="lineno">  970</span><span class="comment"> */</span></div>
<div class="line"><a id="l00971" name="l00971"></a><span class="lineno"><a class="line" href="util__fwd_8hpp.html#a0cc4c82ac54e53b7a8a2431b66ff30df">  971</a></span><span class="preprocessor">#define FLOW_UTIL_WHERE_AM_I_STR() \</span></div>
<div class="line"><a id="l00972" name="l00972"></a><span class="lineno">  972</span><span class="preprocessor">  ::flow::util::get_where_am_i_str(::flow::util::get_last_path_segment \</span></div>
<div class="line"><a id="l00973" name="l00973"></a><span class="lineno">  973</span><span class="preprocessor">                                     (::flow::util::String_view(__FILE__, sizeof(__FILE__) - 1)), \</span></div>
<div class="line"><a id="l00974" name="l00974"></a><span class="lineno">  974</span><span class="preprocessor">                                   ::flow::util::String_view(__FUNCTION__, sizeof(__FUNCTION__) - 1), \</span></div>
<div class="line"><a id="l00975" name="l00975"></a><span class="lineno">  975</span><span class="preprocessor">                                   __LINE__)</span></div>
<div class="line"><a id="l00976" name="l00976"></a><span class="lineno">  976</span><span class="comment"></span> </div>
<div class="line"><a id="l00977" name="l00977"></a><span class="lineno">  977</span><span class="comment">/**</span></div>
<div class="line"><a id="l00978" name="l00978"></a><span class="lineno">  978</span><span class="comment"> * Use this to create a semicolon-safe version of a &quot;void&quot; functional macro definition consisting of at least two</span></div>
<div class="line"><a id="l00979" name="l00979"></a><span class="lineno">  979</span><span class="comment"> * statements; or of one statement that would become two statements by appending a semicolon.</span></div>
<div class="line"><a id="l00980" name="l00980"></a><span class="lineno">  980</span><span class="comment"> *</span></div>
<div class="line"><a id="l00981" name="l00981"></a><span class="lineno">  981</span><span class="comment"> * There may be other use cases where it might be useful, though none more has come to mind as of this writing.</span></div>
<div class="line"><a id="l00982" name="l00982"></a><span class="lineno">  982</span><span class="comment"> * Loosely speaking, IF your sub-statements are always blocks, and you have a &quot;void&quot; functional macro to be used in</span></div>
<div class="line"><a id="l00983" name="l00983"></a><span class="lineno">  983</span><span class="comment"> * the typical way (every use is a statement that looks like a function call), and the macro&#39;s definition is anything</span></div>
<div class="line"><a id="l00984" name="l00984"></a><span class="lineno">  984</span><span class="comment"> * *other* than an expression with an intentionally missing trailing semicolon, THEN you should probably wrap</span></div>
<div class="line"><a id="l00985" name="l00985"></a><span class="lineno">  985</span><span class="comment"> * that would-be macro definition in a FLOW_UTIL_SEMICOLON_SAFE().  However, read on if you want to know rationale</span></div>
<div class="line"><a id="l00986" name="l00986"></a><span class="lineno">  986</span><span class="comment"> * and/or formalities.</span></div>
<div class="line"><a id="l00987" name="l00987"></a><span class="lineno">  987</span><span class="comment"> *</span></div>
<div class="line"><a id="l00988" name="l00988"></a><span class="lineno">  988</span><span class="comment"> * ### Formal use case requirements ###</span></div>
<div class="line"><a id="l00989" name="l00989"></a><span class="lineno">  989</span><span class="comment"> * The following is assumed about every *use* of this macro; behavior is undefined otherwise.</span></div>
<div class="line"><a id="l00990" name="l00990"></a><span class="lineno">  990</span><span class="comment"> *</span></div>
<div class="line"><a id="l00991" name="l00991"></a><span class="lineno">  991</span><span class="comment"> * - The macro&#39;s invocation is the *entire definition* of another macro, M.</span></div>
<div class="line"><a id="l00992" name="l00992"></a><span class="lineno">  992</span><span class="comment"> * - M is a functional macro taking 0 or more arguments (possibly variadic).</span></div>
<div class="line"><a id="l00993" name="l00993"></a><span class="lineno">  993</span><span class="comment"> * - The following is true about every *use* of the macro M:</span></div>
<div class="line"><a id="l00994" name="l00994"></a><span class="lineno">  994</span><span class="comment"> *   - The invocation is written as if M is a free function in the C language, and it is being &quot;called&quot;</span></div>
<div class="line"><a id="l00995" name="l00995"></a><span class="lineno">  995</span><span class="comment"> *     as the *entirety* of the statement containing that &quot;call.&quot;  That is, it must look like this:</span></div>
<div class="line"><a id="l00996" name="l00996"></a><span class="lineno">  996</span><span class="comment"> *</span></div>
<div class="line"><a id="l00997" name="l00997"></a><span class="lineno">  997</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l00998" name="l00998"></a><span class="lineno">  998</span><span class="comment"> *   M(...arg 1 value..., ...arg 2 value..., ...more...); // (Or however many args M actually allows.)</span></div>
<div class="line"><a id="l00999" name="l00999"></a><span class="lineno">  999</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01000" name="l01000"></a><span class="lineno"> 1000</span><span class="comment"> *</span></div>
<div class="line"><a id="l01001" name="l01001"></a><span class="lineno"> 1001</span><span class="comment"> * ### Known use case 1: Macro definition is 2+ statements ###</span></div>
<div class="line"><a id="l01002" name="l01002"></a><span class="lineno"> 1002</span><span class="comment"> * Suppose your macro&#39;s value is a series of two or more statements executing in series without braces `{}`</span></div>
<div class="line"><a id="l01003" name="l01003"></a><span class="lineno"> 1003</span><span class="comment"> * around the whole thing.  Then, in some contexts, invoking that macro as intended might result in</span></div>
<div class="line"><a id="l01004" name="l01004"></a><span class="lineno"> 1004</span><span class="comment"> * unexpected runtime misbehavior that the compiler wouldn&#39;t detect.  A simple example with two</span></div>
<div class="line"><a id="l01005" name="l01005"></a><span class="lineno"> 1005</span><span class="comment"> * expressions as individual statements:</span></div>
<div class="line"><a id="l01006" name="l01006"></a><span class="lineno"> 1006</span><span class="comment"> *</span></div>
<div class="line"><a id="l01007" name="l01007"></a><span class="lineno"> 1007</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01008" name="l01008"></a><span class="lineno"> 1008</span><span class="comment"> *   #define DOUBLE_AND_PRINT(arg) \</span></div>
<div class="line"><a id="l01009" name="l01009"></a><span class="lineno"> 1009</span><span class="comment"> *     arg *= 2;    // Statement 1. \</span></div>
<div class="line"><a id="l01010" name="l01010"></a><span class="lineno"> 1010</span><span class="comment"> *     cout &lt;&lt; arg  // Statement 2.  Note the lacking trailing semicolon (invoker must supply it after &quot;call&quot;). \</span></div>
<div class="line"><a id="l01011" name="l01011"></a><span class="lineno"> 1011</span><span class="comment"> *   DOUBLE_AND_PRINT(x); // No problem. Both statements execute.</span></div>
<div class="line"><a id="l01012" name="l01012"></a><span class="lineno"> 1012</span><span class="comment"> *   if (some_flag)</span></div>
<div class="line"><a id="l01013" name="l01013"></a><span class="lineno"> 1013</span><span class="comment"> *     DOUBLE_AND_PRINT(x); // UNINTENDED BEHAVIOR!  Statement 2 executes regardless of some_flag!</span></div>
<div class="line"><a id="l01014" name="l01014"></a><span class="lineno"> 1014</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01015" name="l01015"></a><span class="lineno"> 1015</span><span class="comment"> *</span></div>
<div class="line"><a id="l01016" name="l01016"></a><span class="lineno"> 1016</span><span class="comment"> * Granted, if the invoker used braces appropriately around the `if` statement body, there&#39;d be no issue, but one</span></div>
<div class="line"><a id="l01017" name="l01017"></a><span class="lineno"> 1017</span><span class="comment"> * cannot always rely on invoker&#39;s good style, especially if the macro is part of a public library API.</span></div>
<div class="line"><a id="l01018" name="l01018"></a><span class="lineno"> 1018</span><span class="comment"> * Solution:</span></div>
<div class="line"><a id="l01019" name="l01019"></a><span class="lineno"> 1019</span><span class="comment"> *</span></div>
<div class="line"><a id="l01020" name="l01020"></a><span class="lineno"> 1020</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01021" name="l01021"></a><span class="lineno"> 1021</span><span class="comment"> *   #define DOUBLE_AND_PRINT(arg) \</span></div>
<div class="line"><a id="l01022" name="l01022"></a><span class="lineno"> 1022</span><span class="comment"> *     FLOW_UTIL_SEMICOLON_SAFE \</span></div>
<div class="line"><a id="l01023" name="l01023"></a><span class="lineno"> 1023</span><span class="comment"> *     ( \</span></div>
<div class="line"><a id="l01024" name="l01024"></a><span class="lineno"> 1024</span><span class="comment"> *       arg *= 2;    // Statement 1. \</span></div>
<div class="line"><a id="l01025" name="l01025"></a><span class="lineno"> 1025</span><span class="comment"> *       cout &lt;&lt; arg; // Statement 2.  Note necessity for trailing semicolon. \</span></div>
<div class="line"><a id="l01026" name="l01026"></a><span class="lineno"> 1026</span><span class="comment"> *     )</span></div>
<div class="line"><a id="l01027" name="l01027"></a><span class="lineno"> 1027</span><span class="comment"> *   DOUBLE_AND_PRINT(x); // No problem.  Both statements execute.</span></div>
<div class="line"><a id="l01028" name="l01028"></a><span class="lineno"> 1028</span><span class="comment"> *   if (some_flag)</span></div>
<div class="line"><a id="l01029" name="l01029"></a><span class="lineno"> 1029</span><span class="comment"> *     DOUBLE_AND_PRINT(x); // No problem.  Both statements execute; or neither one does.</span></div>
<div class="line"><a id="l01030" name="l01030"></a><span class="lineno"> 1030</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01031" name="l01031"></a><span class="lineno"> 1031</span><span class="comment"> *</span></div>
<div class="line"><a id="l01032" name="l01032"></a><span class="lineno"> 1032</span><span class="comment"> * One might ask: Why not simply surround the 2+ statements with braces `{}` to eliminate the problem more simply?</span></div>
<div class="line"><a id="l01033" name="l01033"></a><span class="lineno"> 1033</span><span class="comment"> * Answer: This actually would turn the use case into the following other problematic use case.</span></div>
<div class="line"><a id="l01034" name="l01034"></a><span class="lineno"> 1034</span><span class="comment"> *</span></div>
<div class="line"><a id="l01035" name="l01035"></a><span class="lineno"> 1035</span><span class="comment"> * ### Known use case 2: Required semicolon `;` trailing macro invocation leads to syntax error ###</span></div>
<div class="line"><a id="l01036" name="l01036"></a><span class="lineno"> 1036</span><span class="comment"> * Recall that the premise *requires* invoker to call your macro M like `M();`, meaning they will *always* put</span></div>
<div class="line"><a id="l01037" name="l01037"></a><span class="lineno"> 1037</span><span class="comment"> * a semicolon after the invocation.  Now suppose that doing so will turn one statement (which is M&#39;s definition)</span></div>
<div class="line"><a id="l01038" name="l01038"></a><span class="lineno"> 1038</span><span class="comment"> * into two.  Another way of putting it: Suppose M&#39;s body is already a complete statement, even without the required</span></div>
<div class="line"><a id="l01039" name="l01039"></a><span class="lineno"> 1039</span><span class="comment"> * trailing `;` (and there is no way to make it otherwise; usually [always?] because it ends with a `}`).</span></div>
<div class="line"><a id="l01040" name="l01040"></a><span class="lineno"> 1040</span><span class="comment"> * Then in some contexts it&#39;ll cause a syntax error.  Example:</span></div>
<div class="line"><a id="l01041" name="l01041"></a><span class="lineno"> 1041</span><span class="comment"> *</span></div>
<div class="line"><a id="l01042" name="l01042"></a><span class="lineno"> 1042</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01043" name="l01043"></a><span class="lineno"> 1043</span><span class="comment"> *   #define CHECK_AND_LOG(msg) \</span></div>
<div class="line"><a id="l01044" name="l01044"></a><span class="lineno"> 1044</span><span class="comment"> *     if (filter()) \</span></div>
<div class="line"><a id="l01045" name="l01045"></a><span class="lineno"> 1045</span><span class="comment"> *     { \</span></div>
<div class="line"><a id="l01046" name="l01046"></a><span class="lineno"> 1046</span><span class="comment"> *       log(msg); \</span></div>
<div class="line"><a id="l01047" name="l01047"></a><span class="lineno"> 1047</span><span class="comment"> *     } // Semicolon will always be added right here.</span></div>
<div class="line"><a id="l01048" name="l01048"></a><span class="lineno"> 1048</span><span class="comment"> *   CHECK_AND_LOG(&quot;Hello.&quot;); // No problem.  The empty ; statement introduced is harmless.</span></div>
<div class="line"><a id="l01049" name="l01049"></a><span class="lineno"> 1049</span><span class="comment"> *   if (terminating)</span></div>
<div class="line"><a id="l01050" name="l01050"></a><span class="lineno"> 1050</span><span class="comment"> *     CHECK_AND_LOG(msg); // SYNTAX ERROR!  The empty ; will make the `else` illegal.</span></div>
<div class="line"><a id="l01051" name="l01051"></a><span class="lineno"> 1051</span><span class="comment"> *   else</span></div>
<div class="line"><a id="l01052" name="l01052"></a><span class="lineno"> 1052</span><span class="comment"> *     exit();</span></div>
<div class="line"><a id="l01053" name="l01053"></a><span class="lineno"> 1053</span><span class="comment"> *   ~~~</span></div>
<div class="line"><a id="l01054" name="l01054"></a><span class="lineno"> 1054</span><span class="comment"> *</span></div>
<div class="line"><a id="l01055" name="l01055"></a><span class="lineno"> 1055</span><span class="comment"> * Removing the `;` from the invocation is no solution.  Firstly it&#39;ll confuse many editors that will think the</span></div>
<div class="line"><a id="l01056" name="l01056"></a><span class="lineno"> 1056</span><span class="comment"> * &quot;function call&quot; (really macro invocation) is missing the usual semicolon.  This might cause incorrect</span></div>
<div class="line"><a id="l01057" name="l01057"></a><span class="lineno"> 1057</span><span class="comment"> * auto-indentation in the file and who knows what else.  Code analyzer tools may also be affected.</span></div>
<div class="line"><a id="l01058" name="l01058"></a><span class="lineno"> 1058</span><span class="comment"> * Even ignoring issues where the code is fed into a non-compiler, there are possible flow control problems.</span></div>
<div class="line"><a id="l01059" name="l01059"></a><span class="lineno"> 1059</span><span class="comment"> * In this example it&#39;ll attach the `else` in the invoking code to the inner `if` (from the macro)</span></div>
<div class="line"><a id="l01060" name="l01060"></a><span class="lineno"> 1060</span><span class="comment"> * instead of the outer `if` (in the invoking code) as intended.  Wrapping the body of `CHECK_AND_LOG()` in</span></div>
<div class="line"><a id="l01061" name="l01061"></a><span class="lineno"> 1061</span><span class="comment"> * the proposed wrapper will resolve all stated problems.  (Solution code omitted for brevity and obviousness</span></div>
<div class="line"><a id="l01062" name="l01062"></a><span class="lineno"> 1062</span><span class="comment"> * at this point.)</span></div>
<div class="line"><a id="l01063" name="l01063"></a><span class="lineno"> 1063</span><span class="comment"> *</span></div>
<div class="line"><a id="l01064" name="l01064"></a><span class="lineno"> 1064</span><span class="comment"> * @note Adding this wrapper would slightly adversely affect performance in the complete absence of compiler</span></div>
<div class="line"><a id="l01065" name="l01065"></a><span class="lineno"> 1065</span><span class="comment"> *       optimization, but even the most basic optimizer (one capable of eliminating `if (false)` and similar)</span></div>
<div class="line"><a id="l01066" name="l01066"></a><span class="lineno"> 1066</span><span class="comment"> *       should entirely eliminate any such performance degradation.</span></div>
<div class="line"><a id="l01067" name="l01067"></a><span class="lineno"> 1067</span><span class="comment"> *</span></div>
<div class="line"><a id="l01068" name="l01068"></a><span class="lineno"> 1068</span><span class="comment"> * @param ARG_func_macro_definition</span></div>
<div class="line"><a id="l01069" name="l01069"></a><span class="lineno"> 1069</span><span class="comment"> *        The intended value of a functional macro, such that the &quot;function&quot; it approximates would have</span></div>
<div class="line"><a id="l01070" name="l01070"></a><span class="lineno"> 1070</span><span class="comment"> *        return type `void`.  Behavior is undefined if the value of this parameter ends in a semicolon, or</span></div>
<div class="line"><a id="l01071" name="l01071"></a><span class="lineno"> 1071</span><span class="comment"> *        if the value contains a statement that includes another statement within it that is not a block</span></div>
<div class="line"><a id="l01072" name="l01072"></a><span class="lineno"> 1072</span><span class="comment"> *        (`{ ... }`).  (The rules in the last [English] statement may or may not be strictly necessary,</span></div>
<div class="line"><a id="l01073" name="l01073"></a><span class="lineno"> 1073</span><span class="comment"> *        but requiring these allows me to generalize/reason more straightforwardly.  In any case, one rule is</span></div>
<div class="line"><a id="l01074" name="l01074"></a><span class="lineno"> 1074</span><span class="comment"> *        assumed good style anyway, while the other is simply practical in this context.)</span></div>
<div class="line"><a id="l01075" name="l01075"></a><span class="lineno"> 1075</span><span class="comment"> * @return Code to be used as the entire definition of a macro whose definition would have been</span></div>
<div class="line"><a id="l01076" name="l01076"></a><span class="lineno"> 1076</span><span class="comment"> *         `ARG_func_macro_definition` if not for the resulting compile error or unexpected flow control</span></div>
<div class="line"><a id="l01077" name="l01077"></a><span class="lineno"> 1077</span><span class="comment"> *         effects detailed above.</span></div>
<div class="line"><a id="l01078" name="l01078"></a><span class="lineno"> 1078</span><span class="comment"> */</span></div>
<div class="line"><a id="l01079" name="l01079"></a><span class="lineno"><a class="line" href="util__fwd_8hpp.html#a402a1fb61d3fe4ca6767729e38620d6d"> 1079</a></span><span class="preprocessor">#define FLOW_UTIL_SEMICOLON_SAFE(ARG_func_macro_definition) \</span></div>
<div class="line"><a id="l01080" name="l01080"></a><span class="lineno"> 1080</span><span class="preprocessor">  do \</span></div>
<div class="line"><a id="l01081" name="l01081"></a><span class="lineno"> 1081</span><span class="preprocessor">  { \</span></div>
<div class="line"><a id="l01082" name="l01082"></a><span class="lineno"> 1082</span><span class="preprocessor">    ARG_func_macro_definition \</span></div>
<div class="line"><a id="l01083" name="l01083"></a><span class="lineno"> 1083</span><span class="preprocessor">  } \</span></div>
<div class="line"><a id="l01084" name="l01084"></a><span class="lineno"> 1084</span><span class="preprocessor">  while (false)</span></div>
<div class="line"><a id="l01085" name="l01085"></a><span class="lineno"> 1085</span> </div>
<div class="line"><a id="l01086" name="l01086"></a><span class="lineno"> 1086</span>} <span class="comment">// namespace flow::util</span></div>
<div class="ttc" id="aclassflow_1_1Function_html"><div class="ttname"><a href="classflow_1_1Function.html">flow::Function</a></div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00512">common.hpp:512</a></div></div>
<div class="ttc" id="aclassflow_1_1util_1_1Linked__hash__map_html"><div class="ttname"><a href="classflow_1_1util_1_1Linked__hash__map.html">flow::util::Linked_hash_map</a></div><div class="ttdoc">An object of this class is a map that combines the lookup speed of a boost::unordered_map&lt;&gt; and order...</div><div class="ttdef"><b>Definition:</b> <a href="linked__hash__map_8hpp_source.html#l00075">linked_hash_map.hpp:76</a></div></div>
<div class="ttc" id="aclassflow_1_1util_1_1Linked__hash__set_html"><div class="ttname"><a href="classflow_1_1util_1_1Linked__hash__set.html">flow::util::Linked_hash_set</a></div><div class="ttdoc">An object of this class is a set that combines the lookup speed of an unordered_set&lt;&gt; and ordering an...</div><div class="ttdef"><b>Definition:</b> <a href="linked__hash__set_8hpp_source.html#l00047">linked_hash_set.hpp:48</a></div></div>
<div class="ttc" id="adetail_2util__fwd_8hpp_html"><div class="ttname"><a href="detail_2util__fwd_8hpp.html">util_fwd.hpp</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html"><div class="ttname"><a href="namespaceflow_1_1util.html">flow::util</a></div><div class="ttdoc">Flow module containing miscellaneous general-use facilities that don't fit into any other Flow module...</div><div class="ttdef"><b>Definition:</b> <a href="basic__blob_8hpp_source.html#l00028">basic_blob.hpp:29</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a015b84cfa3076b8e75d16ec44a5514a3"><div class="ttname"><a href="namespaceflow_1_1util.html#a015b84cfa3076b8e75d16ec44a5514a3">flow::util::Lock_guard_recursive</a></div><div class="ttdeci">boost::unique_lock&lt; Mutex_recursive &gt; Lock_guard_recursive</div><div class="ttdoc">(Deprecated given C++1x) Short-hand for advanced-capability RAII lock guard for Mutex_recursive mutex...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00291">util_fwd.hpp:291</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a024ddda9acb2b66f2a1b35cdb0c016aa"><div class="ttname"><a href="namespaceflow_1_1util.html#a024ddda9acb2b66f2a1b35cdb0c016aa">flow::util::in_closed_open_range</a></div><div class="ttdeci">bool in_closed_open_range(T const &amp;min_val, T const &amp;val, T const &amp;max_val)</div><div class="ttdoc">Returns true if and only if the given value is within the given range, given as a [low,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00287">util.hpp:287</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a03984e29450abf9cf287c501d6c8f866"><div class="ttname"><a href="namespaceflow_1_1util.html#a03984e29450abf9cf287c501d6c8f866">flow::util::key_exists</a></div><div class="ttdeci">bool key_exists(const Container &amp;container, const typename Container::key_type &amp;key)</div><div class="ttdoc">Returns true if and only if the given key is present at least once in the given associative container...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00301">util.hpp:301</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a0955a29930075ac1fe393896c089b911"><div class="ttname"><a href="namespaceflow_1_1util.html#a0955a29930075ac1fe393896c089b911">flow::util::beautify_chrono_ostream</a></div><div class="ttdeci">void beautify_chrono_ostream(std::ostream *os_ptr)</div><div class="ttdoc">Sets certain chrono-related formatting on the given ostream that results in a consistent,...</div><div class="ttdef"><b>Definition:</b> <a href="util_8cpp_source.html#l00173">util.cpp:173</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a09a032f8e1e77a3afc0b7df115a773e1"><div class="ttname"><a href="namespaceflow_1_1util.html#a09a032f8e1e77a3afc0b7df115a773e1">flow::util::setup_auto_cleanup</a></div><div class="ttdeci">Auto_cleanup setup_auto_cleanup(const Cleanup_func &amp;func)</div><div class="ttdoc">Provides a way to execute arbitrary (cleanup) code at the exit of the current block.</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00307">util.hpp:307</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a0a4e7b2d3107bd630e0dc0c0b8f2e4de"><div class="ttname"><a href="namespaceflow_1_1util.html#a0a4e7b2d3107bd630e0dc0c0b8f2e4de">flow::util::Thread_id</a></div><div class="ttdeci">Thread::id Thread_id</div><div class="ttdoc">Short-hand for an OS-provided ID of a util::Thread.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00090">util_fwd.hpp:90</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a0a873d1abeac7a29822e940adf4f06c9"><div class="ttname"><a href="namespaceflow_1_1util.html#a0a873d1abeac7a29822e940adf4f06c9">flow::util::sequence_to_inverted_lookup_map</a></div><div class="ttdeci">void sequence_to_inverted_lookup_map(Sequence const &amp;src_seq, Map *target_map, const Function&lt; typename Map::mapped_type(size_t)&gt; &amp;idx_to_map_val_func)</div><div class="ttdoc">Similar to the 2-arg overload of sequence_to_inverted_lookup_map() but with the ability to store a va...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00391">util.hpp:392</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a0f681afaf67a0f917cf43a7ae893a015"><div class="ttname"><a href="namespaceflow_1_1util.html#a0f681afaf67a0f917cf43a7ae893a015">flow::util::to_mbit_per_sec</a></div><div class="ttdeci">double to_mbit_per_sec(N_items items_per_time, size_t bits_per_item)</div><div class="ttdoc">Utility that converts a bandwidth in arbitrary units in both numerator and denominator to the same ba...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00237">util.hpp:237</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a16357344c21456b86b7de3085e2661a2"><div class="ttname"><a href="namespaceflow_1_1util.html#a16357344c21456b86b7de3085e2661a2">flow::util::buffers_dump_string</a></div><div class="ttdeci">std::string buffers_dump_string(const Const_buffer_sequence &amp;data, const std::string &amp;indentation, size_t bytes_per_line)</div><div class="ttdoc">Identical to buffers_to_ostream() but returns an std::string instead of writing to a given ostream.</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00506">util.hpp:506</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a18a29d6a6e65c3b96c52b5cad5971266"><div class="ttname"><a href="namespaceflow_1_1util.html#a18a29d6a6e65c3b96c52b5cad5971266">flow::util::istream_to_enum</a></div><div class="ttdeci">Enum istream_to_enum(std::istream *is_ptr, Enum enum_default, Enum enum_sentinel, bool accept_num_encoding, bool case_sensitive, Enum enum_lowest)</div><div class="ttdoc">Deserializes an enum class value from a standard input stream.</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00523">util.hpp:523</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a2ed0f6ab85f5df463bb10913b0764540"><div class="ttname"><a href="namespaceflow_1_1util.html#a2ed0f6ab85f5df463bb10913b0764540">flow::util::Ip_address_v6</a></div><div class="ttdeci">boost::asio::ip::address_v6 Ip_address_v6</div><div class="ttdoc">Short-hand for the IPv6 address type.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00212">util_fwd.hpp:212</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a331b3b73d9d633101d6f0ebc1c829701"><div class="ttname"><a href="namespaceflow_1_1util.html#a331b3b73d9d633101d6f0ebc1c829701">flow::util::Ip_address_v4</a></div><div class="ttdeci">boost::asio::ip::address_v4 Ip_address_v4</div><div class="ttdoc">Short-hand for the IPv4 address type.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00210">util_fwd.hpp:210</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a34ed70fa4de81a4fdb9234bfb5a3a914"><div class="ttname"><a href="namespaceflow_1_1util.html#a34ed70fa4de81a4fdb9234bfb5a3a914">flow::util::subtract_with_floor</a></div><div class="ttdeci">bool subtract_with_floor(Minuend *minuend, const Subtrahend &amp;subtrahend, const Minuend &amp;floor)</div><div class="ttdoc">Performs *minuend -= subtrahend, subject to a floor of floor.</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00324">util.hpp:324</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a418b56a178c07100eef78da5c9d6ee7a"><div class="ttname"><a href="namespaceflow_1_1util.html#a418b56a178c07100eef78da5c9d6ee7a">flow::util::deep_size</a></div><div class="ttdeci">size_t deep_size(const std::string &amp;val)</div><div class="ttdoc">Estimate of memory footprint of the given value, including memory allocated on its behalf – but exclu...</div><div class="ttdef"><b>Definition:</b> <a href="util_8cpp_source.html#l00186">util.cpp:186</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a5d2247b715da63e4b960909561b90ae7"><div class="ttname"><a href="namespaceflow_1_1util.html#a5d2247b715da63e4b960909561b90ae7">flow::util::Lock_guard</a></div><div class="ttdeci">boost::unique_lock&lt; Mutex &gt; Lock_guard</div><div class="ttdoc">Short-hand for advanced-capability RAII lock guard for any mutex, ensuring exclusive ownership of tha...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00265">util_fwd.hpp:265</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a62b5ba6d6a549ac20e2c055e72bef421"><div class="ttname"><a href="namespaceflow_1_1util.html#a62b5ba6d6a549ac20e2c055e72bef421">flow::util::Mutex_shared_non_recursive</a></div><div class="ttdeci">boost::shared_mutex Mutex_shared_non_recursive</div><div class="ttdoc">Short-hand for non-reentrant, shared-or-exclusive mutex.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00243">util_fwd.hpp:243</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a67eecb5096dabfaff3d02c419b304540"><div class="ttname"><a href="namespaceflow_1_1util.html#a67eecb5096dabfaff3d02c419b304540">flow::util::size_unit_convert</a></div><div class="ttdeci">size_t size_unit_convert(From num_froms)</div><div class="ttdoc">Answers the question what's the smallest integer number of Tos sufficient to verbatim store the given...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00346">util.hpp:346</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a685b86585da2fa5186f51854e7ae1561"><div class="ttname"><a href="namespaceflow_1_1util.html#a685b86585da2fa5186f51854e7ae1561">flow::util::ostream_op_string</a></div><div class="ttdeci">std::string ostream_op_string(T const &amp;... ostream_args)</div><div class="ttdoc">Equivalent to ostream_op_to_string() but returns a new string by value instead of writing to the call...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00381">util.hpp:381</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a689388b6eb7e760933d99381d65cacca"><div class="ttname"><a href="namespaceflow_1_1util.html#a689388b6eb7e760933d99381d65cacca">flow::util::Lock_guard_shared_non_recursive_sh</a></div><div class="ttdeci">boost::shared_lock&lt; Mutex_shared_non_recursive &gt; Lock_guard_shared_non_recursive_sh</div><div class="ttdoc">(Deprecated given C++1x) Short-hand for shared mode advanced-capability RAII lock guard for Mutex_sha...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00300">util_fwd.hpp:300</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a6b7316b3ed6d89f54c91e17c2aab101e"><div class="ttname"><a href="namespaceflow_1_1util.html#a6b7316b3ed6d89f54c91e17c2aab101e">flow::util::ceil_div</a></div><div class="ttdeci">Integer ceil_div(Integer dividend, Integer divisor)</div><div class="ttdoc">Returns the result of the given non-negative integer divided by a positive integer,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00258">util.hpp:258</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a71eaa4ab6a2673ed34fa8989c47a7bc0"><div class="ttname"><a href="namespaceflow_1_1util.html#a71eaa4ab6a2673ed34fa8989c47a7bc0">flow::util::swap</a></div><div class="ttdeci">void swap(Basic_blob&lt; Allocator, S_SHARING_ALLOWED &gt; &amp;blob1, Basic_blob&lt; Allocator, S_SHARING_ALLOWED &gt; &amp;blob2, log::Logger *logger_ptr)</div><div class="ttdoc">Equivalent to blob1.swap(blob2).</div><div class="ttdef"><b>Definition:</b> <a href="basic__blob_8hpp_source.html#l01666">basic_blob.hpp:1666</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a733448fee07c2a77e343a3f1590ff82e"><div class="ttname"><a href="namespaceflow_1_1util.html#a733448fee07c2a77e343a3f1590ff82e">flow::util::in_open_open_range</a></div><div class="ttdeci">bool in_open_open_range(T const &amp;min_val, T const &amp;val, T const &amp;max_val)</div><div class="ttdoc">Returns true if and only if the given value is within the given range, given as a (low,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00295">util.hpp:295</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a8ae762ea4f743a98a73953d7f9ec2164"><div class="ttname"><a href="namespaceflow_1_1util.html#a8ae762ea4f743a98a73953d7f9ec2164">flow::util::in_open_closed_range</a></div><div class="ttdeci">bool in_open_closed_range(T const &amp;min_val, T const &amp;val, T const &amp;max_val)</div><div class="ttdoc">Returns true if and only if the given value is within the given range, given as a (low,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00279">util.hpp:279</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a8afd30c50bcd670d45442df49d1da484"><div class="ttname"><a href="namespaceflow_1_1util.html#a8afd30c50bcd670d45442df49d1da484">flow::util::ostream_op_to_string</a></div><div class="ttdeci">void ostream_op_to_string(std::string *target_str, T const &amp;... ostream_args)</div><div class="ttdoc">Writes to the specified string, as if the given arguments were each passed, via &lt;&lt; in sequence,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00367">util.hpp:367</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a9495b3e37e9d27bcc7767a4b6ce87ff4"><div class="ttname"><a href="namespaceflow_1_1util.html#a9495b3e37e9d27bcc7767a4b6ce87ff4">flow::util::Lock_guard_non_recursive</a></div><div class="ttdeci">boost::unique_lock&lt; Mutex_non_recursive &gt; Lock_guard_non_recursive</div><div class="ttdoc">(Deprecated given C++1x) Short-hand for advanced-capability RAII lock guard for Mutex_non_recursive m...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00283">util_fwd.hpp:283</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a9c7a5df07c2e86c788de9e6bbaee77d5"><div class="ttname"><a href="namespaceflow_1_1util.html#a9c7a5df07c2e86c788de9e6bbaee77d5">flow::util::Mutex_recursive</a></div><div class="ttdeci">boost::recursive_mutex Mutex_recursive</div><div class="ttdoc">Short-hand for reentrant, exclusive mutex.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00218">util_fwd.hpp:218</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a9df3cc2f3aec0c0353443b9d6c81e638"><div class="ttname"><a href="namespaceflow_1_1util.html#a9df3cc2f3aec0c0353443b9d6c81e638">flow::util::Lock_guard_shared_non_recursive_ex</a></div><div class="ttdeci">boost::unique_lock&lt; Mutex_shared_non_recursive &gt; Lock_guard_shared_non_recursive_ex</div><div class="ttdoc">(Deprecated given C++1x) Short-hand for exclusive mode advanced-capability RAII lock guard for Mutex_...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00309">util_fwd.hpp:309</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_a9e5fae573be960434c4c9dacd48c9c11"><div class="ttname"><a href="namespaceflow_1_1util.html#a9e5fae573be960434c4c9dacd48c9c11">flow::util::Lock_guard_noop_shared_non_recursive_sh</a></div><div class="ttdeci">boost::shared_lock&lt; Mutex_noop_shared_non_recursive &gt; Lock_guard_noop_shared_non_recursive_sh</div><div class="ttdoc">(Deprecated given C++1x) Equivalent to Lock_guard_shared_non_recursive_sh but applied to Mutex_noop_s...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00318">util_fwd.hpp:318</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_aa132928b364caefca5c3821e019924bf"><div class="ttname"><a href="namespaceflow_1_1util.html#aa132928b364caefca5c3821e019924bf">flow::util::buffers_to_ostream</a></div><div class="ttdeci">std::ostream &amp; buffers_to_ostream(std::ostream &amp;os, const Const_buffer_sequence &amp;data, const std::string &amp;indentation, size_t bytes_per_line)</div><div class="ttdoc">Writes a multi- or single-line string representation of the provided binary data to an output stream,...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00413">util.hpp:413</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_aa59354ab408e978c8a7bda1a4706924e"><div class="ttname"><a href="namespaceflow_1_1util.html#aa59354ab408e978c8a7bda1a4706924e">flow::util::Strand</a></div><div class="ttdeci">Task_engine::strand Strand</div><div class="ttdoc">Short-hand for boost.asio strand, an ancillary class that works with Task_engine for advanced task sc...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00138">util_fwd.hpp:138</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ab10bc9e8bef148f875aa743fe0852743"><div class="ttname"><a href="namespaceflow_1_1util.html#ab10bc9e8bef148f875aa743fe0852743">flow::util::in_closed_range</a></div><div class="ttdeci">bool in_closed_range(T const &amp;min_val, T const &amp;val, T const &amp;max_val)</div><div class="ttdoc">Returns true if and only if the given value is within the given range, inclusive.</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00271">util.hpp:271</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ab22fd89e165a9e6deaa174bc0dfdc8de"><div class="ttname"><a href="namespaceflow_1_1util.html#ab22fd89e165a9e6deaa174bc0dfdc8de">flow::util::Auto_cleanup</a></div><div class="ttdeci">boost::shared_ptr&lt; void &gt; Auto_cleanup</div><div class="ttdoc">Helper type for setup_auto_cleanup().</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00205">util_fwd.hpp:205</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ac3e89a8a271b0ddc76ac2a0ce488dea4"><div class="ttname"><a href="namespaceflow_1_1util.html#ac3e89a8a271b0ddc76ac2a0ce488dea4">flow::util::Task_engine</a></div><div class="ttdeci">boost::asio::io_context Task_engine</div><div class="ttdoc">Short-hand for boost.asio event service, the central class of boost.asio.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00135">util_fwd.hpp:135</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ac4f0492f15f46f70581feac50b9217ee"><div class="ttname"><a href="namespaceflow_1_1util.html#ac4f0492f15f46f70581feac50b9217ee">flow::util::Shared_lock_guard</a></div><div class="ttdeci">boost::shared_lock&lt; Shared_mutex &gt; Shared_lock_guard</div><div class="ttdoc">Short-hand for shared mode advanced-capability RAII lock guard, particuarly for Mutex_shared_non_recu...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00275">util_fwd.hpp:275</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ad92ad411feccf73908abe6ed130d48f5"><div class="ttname"><a href="namespaceflow_1_1util.html#ad92ad411feccf73908abe6ed130d48f5">flow::util::time_since_posix_epoch</a></div><div class="ttdeci">boost::chrono::microseconds time_since_posix_epoch()</div><div class="ttdoc">Get the current POSIX (Unix) time as a duration from the Epoch time point.</div><div class="ttdef"><b>Definition:</b> <a href="util_8cpp_source.html#l00147">util.cpp:147</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_add56211dee74c212c19028f1ded2a785"><div class="ttname"><a href="namespaceflow_1_1util.html#add56211dee74c212c19028f1ded2a785">flow::util::Lock_guard_noop_shared_non_recursive_ex</a></div><div class="ttdeci">boost::unique_lock&lt; Mutex_noop_shared_non_recursive &gt; Lock_guard_noop_shared_non_recursive_ex</div><div class="ttdoc">(Deprecated given C++1x) Equivalent to Lock_guard_shared_non_recursive_ex but applied to Mutex_noop_s...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00327">util_fwd.hpp:327</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_add6ade273326f27eaf9bfd170a909626"><div class="ttname"><a href="namespaceflow_1_1util.html#add6ade273326f27eaf9bfd170a909626">flow::util::Mutex_non_recursive</a></div><div class="ttdeci">boost::mutex Mutex_non_recursive</div><div class="ttdoc">Short-hand for non-reentrant, exclusive mutex. (&quot;Reentrant&quot; = one can lock an already-locked-in-that-...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00215">util_fwd.hpp:215</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_ae7416d64d2989051104bb396e28e15e6"><div class="ttname"><a href="namespaceflow_1_1util.html#ae7416d64d2989051104bb396e28e15e6">flow::util::Timer</a></div><div class="ttdeci">boost::asio::basic_waitable_timer&lt; Fine_clock &gt; Timer</div><div class="ttdoc">boost.asio timer.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00202">util_fwd.hpp:202</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_aeee121f0277371517fd2f5c3a20d8112"><div class="ttname"><a href="namespaceflow_1_1util.html#aeee121f0277371517fd2f5c3a20d8112">flow::util::Mutex_noop_shared_non_recursive</a></div><div class="ttdeci">boost::null_mutex Mutex_noop_shared_non_recursive</div><div class="ttdoc">Short-hand for a mutex type equivalent to util::Mutex_shared_non_recursive – except that the lock/unl...</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00251">util_fwd.hpp:251</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_af030c3119f060a9630afca31098a78a5"><div class="ttname"><a href="namespaceflow_1_1util.html#af030c3119f060a9630afca31098a78a5">flow::util::Thread</a></div><div class="ttdeci">boost::thread Thread</div><div class="ttdoc">Short-hand for standard thread class.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00078">util_fwd.hpp:78</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_af1b28edb7bad743c1c77f6b982cc3196"><div class="ttname"><a href="namespaceflow_1_1util.html#af1b28edb7bad743c1c77f6b982cc3196">flow::util::Udp_endpoint</a></div><div class="ttdeci">boost::asio::ip::udp::endpoint Udp_endpoint</div><div class="ttdoc">Short-hand for the UDP endpoint (IP/port) type.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00208">util_fwd.hpp:208</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_af92e6183c2071f4166d4b5a91f50d70c"><div class="ttname"><a href="namespaceflow_1_1util.html#af92e6183c2071f4166d4b5a91f50d70c">flow::util::feed_args_to_ostream</a></div><div class="ttdeci">void feed_args_to_ostream(std::ostream *os, T1 const &amp;ostream_arg1, T_rest const &amp;... remaining_ostream_args)</div><div class="ttdoc">&quot;Induction step&quot; version of variadic function template that simply outputs arguments 2+ via &lt;&lt; to the...</div><div class="ttdef"><b>Definition:</b> <a href="util_2util_8hpp_source.html#l00352">util.hpp:352</a></div></div>
</div><!-- fragment --></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Mar 28 2025 22:55:35 for Flow by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
